diff --git a/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md b/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md index 31171ed2b546d..09085aba04e80 100644 --- a/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md +++ b/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md @@ -44,11 +44,12 @@ Also, remove this comment before submitting the issue. - C# - Core - Core .NET libraries +- Cryptography - Data - Debugger - Deployment for .NET Core - Globalization -- interop +- Interop - JIT - LINQ - Managed Extensibility Framework (MEF) diff --git a/docs/architecture/serverless/azure-functions.md b/docs/architecture/serverless/azure-functions.md index 7590b818f4199..25af51f990d4d 100644 --- a/docs/architecture/serverless/azure-functions.md +++ b/docs/architecture/serverless/azure-functions.md @@ -3,7 +3,7 @@ title: Azure Functions - Serverless apps description: Azure functions provide serverless capabilities across multiple languages (C#, JavaScript, Java) and platforms to provide event-driven instant scale code. author: JEREMYLIKNESS ms.author: jeliknes -ms.date: 06/26/2018 +ms.date: 04/06/2020 --- # Azure Functions @@ -11,36 +11,23 @@ Azure functions provide a serverless compute experience. A function is invoked b ![Azure functions logo](./media/azure-functions-logo.png) -There are two versions of the Azure Functions framework. The legacy version supports the full .NET Framework and the new runtime supports cross-platform .NET Core applications. Additional languages besides C# such as JavaScript, F#, and Java are supported. Functions created in the portal provide a rich scripting syntax. Functions created as standalone projects can be deployed with full platform support and capabilities. +The current runtime version 3.0 supports cross-platform .NET Core 3.1 applications. Additional languages besides C# such as JavaScript, F#, and Java are supported. Functions created in the portal provide a rich scripting syntax. Functions created as standalone projects can be deployed with full platform support and capabilities. For more information, see [Azure Functions documentation](https://docs.microsoft.com/azure/azure-functions). -## Functions v1 vs. v2 - -There are two versions of the Azure Functions runtime: 1.x and 2.x. Version 1.x is generally available (GA). It supports .NET development from the portal or Windows machines and uses the .NET Framework. 1.x supports C#, JavaScript, and F#, with experimental support for Python, PHP, TypeScript, Batch, Bash, and PowerShell. - -[Version 2.x is also generally available now](https://azure.microsoft.com/blog/introducing-azure-functions-2-0/). It leverages .NET Core and supports cross-platform development on Windows, macOS, and Linux machines. 2.x adds first-class support for Java but doesn't yet directly support any of the experimental languages. Version 2.x uses a new binding extensibility model that enables third-party extensions to the platform, independent versioning of bindings, and a more streamlined execution environment. - -> **There is a known issue in 1.x with [binding redirect support](https://github.com/Azure/azure-functions-host/issues/992).** The issue is specific to .NET development. Projects with dependencies on libraries that are a different version from the libraries included in the runtime are impacted. The functions team has committed to making concrete progress on the problem. The team will address binding redirects in 2.x before it goes into general availability. The official team statement with suggested fixes and workarounds is available here: [Assembly resolution in Azure Functions](https://github.com/Azure/azure-functions-host/wiki/Assembly-Resolution-in-Azure-Functions). - -For more information, see [Compare 1.x and 2.x](https://docs.microsoft.com/azure/azure-functions/functions-versions). - ## Programming language support -The following languages are supported either in general availability (GA), preview, or experimental. - -|Language |1.x |2.x | -|--------------|------------|---------| -|**C#** |GA |Preview | -|**JavaScript**|GA |Preview | -|**F#** |GA | | -|**Java** | |Preview | -|**Python** |Experimental| | -|**PHP** |Experimental| | -|**TypeScript**|Experimental| | -|**Batch** |Experimental| | -|**Bash** |Experimental| | -|**PowerShell**|Experimental| | +The following languages are all supported in general availability (GA). + +|Language |Supported runtimes| +|--------------|------------------| +|**C#** |.NET Core 3.1 | +|**JavaScript**|Node 10 & 12 | +|**F#** |.NET Core 3.1 | +|**Java** |Java 8 | +|**Python** |Python 3.6, 3.7, & 3.8| +|**TypeScript**|Node 10 & 12 (via JavaScript)| +|**PowerShell**|PowerShell Core 6| For more information, see [Supported languages](https://docs.microsoft.com/azure/azure-functions/supported-languages). @@ -48,6 +35,8 @@ For more information, see [Supported languages](https://docs.microsoft.com/azure Functions are backed by an *app service plan*. The plan defines the resources used by the functions app. You can assign plans to a region, determine the size and number of virtual machines that will be used, and pick a pricing tier. For a true serverless approach, function apps may use the **consumption** plan. The consumption plan will scale the back end automatically based on load. +Another hosting option for function apps is the [Premium plan](https://docs.microsoft.com/azure/azure-functions/functions-premium-plan). This plan provides an "always on" instance to avoid cold start, supports advanced features like VNet connectivity, and runs on premium hardware. + For more information, see [App service plans](https://docs.microsoft.com/azure/app-service/azure-web-sites-web-hosting-plans-in-depth-overview). ## Create your first function @@ -121,58 +110,6 @@ The example is a simple function that takes the name of the file that was modifi For a full list of triggers and bindings, see [Azure Functions triggers and bindings concepts](https://docs.microsoft.com/azure/azure-functions/functions-triggers-bindings). -## Proxies - -Proxies provide redirect functionality for your application. Proxies expose an endpoint and map that endpoint to another resource. With proxies, you can: - -- Reroute an incoming request to another endpoint. -- Modify the incoming request before it's passed along. -- Modify or provide a response. - -Proxies are used for scenarios such as: - -- Simplifying, shortening, or changing the URL. -- Providing a consistent API prefix to multiple back-end services. -- Mocking a response to an endpoint being developed. -- Providing a static response to a well-known endpoint. -- Keeping an API endpoint consistent while the back end is moved or migrated. - -Proxies are stored as JSON definitions. Here is an example: - -```json -{ - "$schema": "http://json.schemastore.org/proxies", - "proxies": { - "Domain Redirect": { - "matchCondition": { - "route": "/{shortUrl}" - }, - "backendUri": "http://%WEBSITE_HOSTNAME%/api/UrlRedirect/{shortUrl}" - }, - "Root": { - "matchCondition": { - "route": "/" - }, - "responseOverrides": { - "response.statusCode": "301", - "response.statusReason": "Moved Permanently", - "response.headers.location": "https://docs.microsoft.com/" - } - } - } -} -``` - -The `Domain Redirect` proxy takes a shortened route and maps it to the longer function resource. The transformation looks like: - -`https://--shorturl--/123` -> `https://--longurl--.azurewebsites.net/api/UrlRedirect/123` - -The `Root` proxy takes anything sent to the root URL (`https://--shorturl--/`) and redirects it to the documentation site. - -An example of using proxies is shown in the video [Azure: Bring your app to the cloud with serverless Azure Functions](https://channel9.msdn.com/events/Connect/2017/E102). In real time, an ASP.NET Core application running on local SQL Server is migrated to the Azure Cloud. Proxies are used to help refactor a traditional Web API project to use functions. - -For more information about Proxies, see [Work with Azure Functions Proxies](https://docs.microsoft.com/azure/azure-functions/functions-proxies). - >[!div class="step-by-step"] >[Previous](azure-serverless-platform.md) >[Next](application-insights.md) diff --git a/docs/architecture/serverless/event-grid.md b/docs/architecture/serverless/event-grid.md index 3502843043992..f6f874701a37d 100644 --- a/docs/architecture/serverless/event-grid.md +++ b/docs/architecture/serverless/event-grid.md @@ -3,7 +3,7 @@ title: Azure Event Grid - Serverless apps description: Azure Event Grid is a serverless solution for reliable event delivery and routing at massive scale on a pay-per-event model. author: JEREMYLIKNESS ms.author: jeliknes -ms.date: 06/26/2018 +ms.date: 04/06/2020 --- # Event Grid @@ -126,14 +126,12 @@ In this chapter you learned about the Azure serverless platform that is composed - [Azure Logic Apps](https://docs.microsoft.com/azure/logic-apps) - [Azure Service Bus](https://docs.microsoft.com/azure/service-bus-messaging) - [Azure Table Storage](https://docs.microsoft.com/azure/cosmos-db/table-storage-overview) -- [Compare functions 1.x and 2.x](https://docs.microsoft.com/azure/azure-functions/functions-versions) - [Connecting to on-premises data sources with Azure On-premises Data Gateway](https://docs.microsoft.com/azure/analysis-services/analysis-services-gateway) - [Create your first function in the Azure portal](https://docs.microsoft.com/azure/azure-functions/functions-create-first-azure-function) - [Create your first function using the Azure CLI](https://docs.microsoft.com/azure/azure-functions/functions-create-first-azure-function-azure-cli) - [Create your first function using Visual Studio](https://docs.microsoft.com/azure/azure-functions/functions-create-your-first-function-visual-studio) - [Functions supported languages](https://docs.microsoft.com/azure/azure-functions/supported-languages) - [Monitor Azure Functions](https://docs.microsoft.com/azure/azure-functions/functions-monitoring) -- [Work with Azure Functions Proxies](https://docs.microsoft.com/azure/azure-functions/functions-proxies) >[!div class="step-by-step"] >[Previous](logic-apps.md) diff --git a/docs/architecture/serverless/index.md b/docs/architecture/serverless/index.md index 8fb41b2ec8e27..4511bd77af6f5 100644 --- a/docs/architecture/serverless/index.md +++ b/docs/architecture/serverless/index.md @@ -3,14 +3,16 @@ title: "Serverless apps: Architecture, patterns, and Azure implementation" description: Guide to serverless architecture. Learn when, why, and how to implement a serverless architecture (as opposed to Infrastructure as a Service [IaaS] or Platform as a Service [PaaS]) for your enterprise applications. author: JEREMYLIKNESS ms.author: jeliknes -ms.date: 06/26/2018 +ms.date: 04/22/2020 --- # Serverless apps: Architecture, patterns, and Azure implementation -![Screenshot that shows the Serverless Apps e-book cover.](./media/index/serverless-apps-cover.jpg) +![Screenshot that shows the Serverless Apps e-book cover.](./media/index/serverless-apps-cover-v3.png) -> DOWNLOAD available at: +**EDITION v3.0** - Updated to Azure Functions v3 + +> DOWNLOAD available at: PUBLISHED BY @@ -22,7 +24,7 @@ One Microsoft Way Redmond, Washington 98052-6399 -Copyright © 2018 by Microsoft Corporation +Copyright © 2018-2020 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. @@ -38,7 +40,7 @@ All other marks and logos are property of their respective owners. Author: -> **[Jeremy Likness](https://twitter.com/jeremylikness)**, Senior Cloud Advocate, Microsoft Corp. +> **[Jeremy Likness](https://twitter.com/jeremylikness)**, Senior .NET Data Program Manager, Microsoft Corp. Contributor: @@ -92,7 +94,7 @@ IaaS still requires heavy overhead because operations is still responsible for v - Keeping the operating system up-to-date. - Monitoring the application. -The next evolution reduced the overhead by providing Platform as a Service (PaaS). With PaaS, the cloud provider handles operating systems, security patches, and even the required packages to support a specific platform. Instead of building a VM then configuring the .NET Framework and standing up Internet Information Services (IIS) servers, developers simply choose a "platform target" such as "web application" or "API endpoint" and deploy code directly. The infrastructure questions are reduced to: +The next evolution reduced the overhead by providing Platform as a Service (PaaS). With PaaS, the cloud provider handles operating systems, security patches, and even the required packages to support a specific platform. Instead of building a VM then configuring .NET and standing up Internet Information Services (IIS) servers, developers simply choose a "platform target" such as "web application" or "API endpoint" and deploy code directly. The infrastructure questions are reduced to: - What size services are needed? - How do the services scale out (add more servers or nodes)? diff --git a/docs/architecture/serverless/media/index/serverless-apps-cover-v3.png b/docs/architecture/serverless/media/index/serverless-apps-cover-v3.png new file mode 100644 index 0000000000000..d11a6f8d9aa8a Binary files /dev/null and b/docs/architecture/serverless/media/index/serverless-apps-cover-v3.png differ diff --git a/docs/architecture/serverless/serverless-architecture-considerations.md b/docs/architecture/serverless/serverless-architecture-considerations.md index a49988af30249..11ac12984256c 100644 --- a/docs/architecture/serverless/serverless-architecture-considerations.md +++ b/docs/architecture/serverless/serverless-architecture-considerations.md @@ -3,7 +3,7 @@ title: Serverless architecture considerations - Serverless apps description: Understand the challenges of architecting serverless applications, from state management and persistent storage to scale, logging, tracing and diagnostics. author: JEREMYLIKNESS ms.author: jeliknes -ms.date: 06/26/2018 +ms.date: 04/06/2020 --- # Serverless architecture considerations @@ -17,7 +17,7 @@ There are several solutions to adopt state without compromising the benefits of - Use a temporary data store or distributed cache, like Redis - Store state in a database, like SQL or CosmosDB -- Handle state through a workflow engine like durable functions +- Handle state through a workflow engine like [durable functions](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview) The bottom line is that you should be aware of the need for any state management within processes you're considering to implement with serverless. @@ -73,7 +73,7 @@ For more information, see [Implementing the Circuit Breaker pattern](../microser ## Versioning and green/blue deployments -A major benefit of serverless is the ability to upgrade a specific function without having to redeploy the entire application. For upgrades to be successful, functions must be versioned so that services calling them are routed to the correct version of code. A strategy for deploying new versions is also important. A common approach is to use "green/blue deployments." The green deployment is the current function. A new "blue" version is deployed to production and tested. When testing passes, the green and blue versions are swapped so the new version comes live. If any issues are encountered, they can be swapped back. Supporting versioning and green/blue deployments requires a combination of authoring the functions to accommodate version changes and working with the serverless platform to handle deployments. One possible approach is to use proxies, which are described in the [Azure serverless platform](azure-functions.md#proxies) chapter. +A major benefit of serverless is the ability to upgrade a specific function without having to redeploy the entire application. For upgrades to be successful, functions must be versioned so that services calling them are routed to the correct version of code. A strategy for deploying new versions is also important. A common approach is to use "green/blue deployments." The green deployment is the current function. A new "blue" version is deployed to production and tested. When testing passes, the green and blue versions are swapped so the new version comes live. If any issues are encountered, they can be swapped back. Supporting versioning and green/blue deployments requires a combination of authoring the functions to accommodate version changes and working with the serverless platform to handle deployments. >[!div class="step-by-step"] >[Previous](serverless-architecture.md) diff --git a/docs/architecture/serverless/serverless-business-scenarios.md b/docs/architecture/serverless/serverless-business-scenarios.md index 14e74bf41c645..3cab0a92946ae 100644 --- a/docs/architecture/serverless/serverless-business-scenarios.md +++ b/docs/architecture/serverless/serverless-business-scenarios.md @@ -1,95 +1,116 @@ --- title: Sample business scenarios and use cases for serverless apps -description: Learn serverless with a hands-on approach by accessing samples that range from image processing to mobile back ends and ETL pipelines. +description: Learn serverless with a hands-on approach by accessing samples that range from image processing to mobile support and ETL pipelines. author: JEREMYLIKNESS ms.author: jeliknes -ms.date: 06/26/2018 +ms.date: 04/17/2020 --- # Serverless business scenarios and use cases There are many use cases and scenarios for serverless applications. This chapter includes samples that illustrate the different scenarios. The scenarios include links to related documentation and public source code repositories. The samples in this chapter enable you to get started on your own building and implementing serverless solutions. -## Analyze and archive images +## Big data processing -This sample demonstrates serverless events (Event Grid), workflows (Logic App), and code (Azure Functions). It also shows how to integrate with another resource, in this case Cognitive Services for image analysis. +![Map/reduce diagram](https://docs.microsoft.com/samples/azure-samples/durablefunctions-mapreduce-dotnet/big-data-processing-serverless-mapreduce-on-azure/media/mapreducearchitecture.png) -A console application allows you to pass a link to a URL on the web. The app publishes the URL as an event grid message. In parallel, a serverless function app and a logic app subscribe to the message. The serverless function app serializes the image to blob storage. It also stores information in Azure Table Storage. The metadata stores the original image URL and the name of the blob image. The logic app interacts with the Custom Vision API to analyze the image and create a machine-generated caption. The caption is stored in the metadata table. +This example uses serverless to do a map/reduce operation on a big data set. It determines the average speed of New York Yellow taxi trips per day in 2017. -![Analyze and archive images architecture](./media/image-processing-example.png) +[Big Data Processing: Serverless MapReduce on Azure](https://docs.microsoft.com/samples/azure-samples/durablefunctions-mapreduce-dotnet/big-data-processing-serverless-mapreduce-on-azure/) -A separate single page application (SPA) calls a serverless function to get a list of images and metadata. For each image, it calls another function that delivers the image data from the archive. The final result is a gallery with automatic captions. +## Create serverless applications: hands-on lab -![Automated image gallery](./media/automated-image-gallery.png) +Learn how to use functions to execute server-side logic and build serverless architectures. -The full repository and instructions to build the logic app are available here: [Event grid glue](https://github.com/JeremyLikness/Event-Grid-Glue). +- Choosing the best Azure service for your business +- Creating Azure Functions +- Using triggers +- Chaining functions +- Long-running workflows +- Monitoring +- Development, testing, and deployment -## Cross-platform mobile client using Xamarin.Forms and functions +[Create serverless applications](https://docs.microsoft.com/learn/paths/create-serverless-applications/) -See how to implement a simple serverless Azure Function in the Azure Web Portal or in Visual Studio. Build a client with Xamarin.Forms that runs on Android, iOS, and Windows. The application is then refined to use JavaScript Object Notation (JSON) as a communication medium between the server and the mobile clients with a serverless back end. +## Customer reviews -For more information, see [Implementing a simple Azure Function with a Xamarin.Forms client](https://docs.microsoft.com/samples/azure-samples/functions-xamarin-getting-started/implementing-a-simple-azure-function-with-a-xamarinforms-client/). +This sample showcases the new Azure Functions tooling for C# Class Libraries in Visual Studio. Create a website where customers submit product reviews that are stored in Azure storage blobs and CosmosDB. Add an Azure Function to perform automated moderation of the customer reviews using Azure Cognitive Services. Use an Azure storage queue to decouple the website from the function. -## Generate a photo mosaic with serverless image recognition +[Customer Reviews App with Cognitive Services](https://docs.microsoft.com/samples/azure-samples/functions-customer-reviews/customer-reviews-cognitive-services/) -The sample uses Azure Functions and Microsoft Cognitive Services Custom Vision Service to generate a photo mosaic from an input image. The model is trained to recognize images. When an image is uploaded, it recognizes the image and searches with Bing. The original image is recomposed using the search results. +## Docker Linux image support -![Orlando eye photo and mosaic](./media/orlando-eye-both.png) +This sample demonstrates how to create a `Dockerfile` to build and run Azure Functions on a Linux Docker container. -For example, you can train your model with Orlando landmarks, such as the Orlando Eye. Custom Vision will recognize an image of the Orlando Eye, and the function will create a photo mosaic composed of Bing image search results for "Orlando Eye." +[Azure Functions on Linux](https://docs.microsoft.com/samples/azure-samples/functions-linux-custom-image/azure-functions-on-linux-custom-image-tutorial-sample-project/) -For more information, see [Azure Functions photo mosaic generator](https://github.com/Azure-Samples/functions-dotnet-photo-mosaic). +## File processing and validation -## Migrate an existing application to the cloud +This example parses a set of CSV files from hypothetical customers. It ensures that all files required for a customer "batch" are ready, then validates the structure of each file. Different solutions are presented using Azure Functions, Logic Apps, and Durable Functions. -As discussed in previous chapters, it's common to embrace an N-Tier architecture to host your application on-premises. Although migrating resources "as is" using virtual machines is the least risky path to the cloud, many companies choose to use the opportunity to refactor their applications. Fortunately, refactoring doesn't have to be an "all-or-nothing" effort. In fact, it's possible to migrate your app then piecemeal replace components with cloud native counterparts. +[File processing and validation using Azure Functions, Logic Apps, and Durable Functions](https://docs.microsoft.com/samples/azure-samples/serverless-file-validation/file-processing-and-validation-using-azure-functions-logic-apps-and-durable-functions/) -The application uses the proxies feature of Azure Functions to enable refactoring an endpoint from legacy on-premises code to a serverless endpoint. +## Game data visualization -![Migration architecture](./media/migration-architecture.png) +![Game telemetry](https://docs.microsoft.com/samples/azure-samples/gaming-in-editor-telemetry/in-editor-telemetry-visualization/media/points.png) -The proxy provides a single API endpoint that is updated to reroute individual requests as they're moved into serverless functions. +An example of how a developer could implement an in-editor data visualization solution for their game. In fact, an Unreal Engine 4 Plugin and Unity Plugin were developed using this sample as its backend. The service component is game engine agnostic. -You can view a video that walks through the entire migration: [Lift and shift with serverless Azure functions](https://channel9.msdn.com/Events/Connect/2017/E102). Access the sample code: [Bring your own app](https://github.com/JeremyLikness/bring-own-app-connect-17). +[In-editor game telemetry visualization](https://docs.microsoft.com/samples/azure-samples/gaming-in-editor-telemetry/in-editor-telemetry-visualization/) -## Parse a CSV file and insert into a database +## GraphQL -Extract, Transform, and Load (ETL) is a common business function that integrates different systems. Traditional approaches often involve setting up dedicated FTP servers then deploying scheduled jobs to parse files and translate them for business use. Serverless architecture makes the job easier because a trigger can fire when the file is uploaded. Azure Functions tackles tasks like ETL through its ideal composition of small pieces of code that focus on a specific problem. +Create a serverless function that exposes a GraphQL API. -![Screenshot that shows the csv parsing process.](./media/serverless-business-scenarios/csv-parse-database-import.png) +[Serverless functions for GraphQL](https://github.com/softchris/graphql-workshop-dotnet/blob/master/docs/workshop/4.md) -For source code and a hands-on lab, see [CSV import lab](https://github.com/JeremyLikness/azure-fn-file-process-hol). +## Internet of Things (IoT) reliable edge relay -## Shorten links and track metrics +![IoT Architecture](https://docs.microsoft.com/samples/azure-samples/iot-reliable-edge-relay/iot-reliable-edge-relay/media/architecture.png) -Link shortening tools originally helped encode URLs in short twitter posts to accommodate the 140 character limit. They've grown to encompass several uses, most commonly to track click-throughs for analytics. The link shortener scenario is an entirely serverless application that manages links and reports metrics. +This sample implements a new communication protocol to enable reliable upstream communication from IoT devices. It automates data gap detection and backfill. -Azure Functions is used to serve a Single Page Application (SPA) that allows you to paste the long URL and generate short URLs. The URLs are tagged to track things like campaigns (topics) and mediums (such as social networks that the links are posted to). The short code is stored in Azure Table Storage as the key, with the long URL as the value. When you click on the short link, another function looks up the long URL, sends a redirect, and places information about the event on a queue. Another Azure Function processes the queue and places the information into Azure Cosmos DB. +[IoT Reliable Edge Relay](https://docs.microsoft.com/samples/azure-samples/iot-reliable-edge-relay/iot-reliable-edge-relay/) -![Link shortener architecture](./media/link-shortener-architecture.png) +## Microservices reference architecture -You can then create a Power BI dashboard to gather insights about the data collected. On the back end, Application Insights provides important metrics. Telemetry includes how long it takes for the average user to redirect and how long it takes to access Azure Table Storage. +![Reference architecture](https://docs.microsoft.com/samples/azure-samples/serverless-microservices-reference-architecture/serverless-microservices-reference-architecture/media/macro-architecture.png) -![Power BI example](./media/power-bi-example.png) +A reference architecture that walks you through the decision-making process involved in designing, developing, and delivering the Rideshare by Relecloud application (a fictitious company). It includes hands-on instructions for configuring and deploying all of the architecture's components. -The full link shortener repository with instructions is available here: [Serverless URL shortener](https://github.com/jeremylikness/serverless-url-shortener). You can read about a simplified version here: [Azure Storage for serverless .NET apps in minutes](https://devblogs.microsoft.com/aspnet/azure-storage-for-serverless-net-apps-in-minutes/). +[Serverless Microservices reference architecture](https://docs.microsoft.com/samples/azure-samples/serverless-microservices-reference-architecture/serverless-microservices-reference-architecture/) -## Verify device connectivity using a ping +## Migrate console apps to serverless -The sample consists of an Azure IoT Hub and an Azure Function. A new message on the IoT Hub triggers the Azure Function. The serverless code sends the same message content back to the device that sent it. The project has all the code and deployment configuration needed for the solution. +This sample is a generic function (`.csx` file) that can be used to convert any console application to an HTTP web service in Azure Functions. All you have to do is edit a configuration file and specify what input parameters will be passed as arguments to the `.exe`. -For more information, see [Azure IoT Hub ping](https://github.com/Azure-Samples/iot-hub-node-ping). +[Run Console Apps on Azure Functions](https://docs.microsoft.com/samples/azure-samples/functions-dotnet-migrating-console-apps/run-console-apps-on-azure-functions/) + +## Serverless for mobile + +Azure Functions are easy to implement and maintain, and accessible through HTTP. They are a great way to implement an API for a mobile application. Microsoft offers great cross-platform tools for iOS, Android, and Windows with Xamarin. As such, Xamarin and Azure Functions are working great together. This article shows how to implement an Azure Function in the Azure Web Portal or in Visual Studio at first, and build a cross-platform client with Xamarin.Forms, running on Android, iOS, and Windows. + +[Implementing a simple Azure Function with a Xamarin.Forms client](https://docs.microsoft.com/samples/azure-samples/functions-xamarin-getting-started/implementing-a-simple-azure-function-with-a-xamarinforms-client/) + +## Serverless messaging + +This sample shows how to utilize Durable Functions' fan out pattern to load an arbitrary number of messages across any number of sessions/partitions. It targets Service Bus, Event Hubs, or Storage Queues. The sample also adds the ability to consume those messages with another Azure Function and load the resulting timing data in to another Event Hub. The data is then ingested into analytics services like Azure Data Explorer. + +[Produce and Consume messages through Service Bus, Event Hubs, and Storage Queues with Azure Functions](https://docs.microsoft.com/samples/azure-samples/durable-functions-producer-consumer/product-consume-messages-az-functions/) ## Recommended resources -- [Azure Functions photo mosaic generator](https://github.com/Azure-Samples/functions-dotnet-photo-mosaic) -- [Azure IoT Hub ping](https://github.com/Azure-Samples/iot-hub-node-ping) -- [Azure Storage for serverless .NET apps in minutes](https://devblogs.microsoft.com/aspnet/azure-storage-for-serverless-net-apps-in-minutes/) -- [Bring your own app](https://github.com/JeremyLikness/bring-own-app-connect-17) -- [CSV import lab](https://github.com/JeremyLikness/azure-fn-file-process-hol) -- [Event grid glue](https://github.com/JeremyLikness/Event-Grid-Glue) +- [Azure Functions on Linux](https://docs.microsoft.com/samples/azure-samples/functions-linux-custom-image/azure-functions-on-linux-custom-image-tutorial-sample-project/) +- [Big Data Processing: Serverless MapReduce on Azure](https://docs.microsoft.com/samples/azure-samples/durablefunctions-mapreduce-dotnet/big-data-processing-serverless-mapreduce-on-azure/) +- [Create serverless applications](https://docs.microsoft.com/learn/paths/create-serverless-applications/) +- [Customer Reviews App with Cognitive Services](https://docs.microsoft.com/samples/azure-samples/functions-customer-reviews/customer-reviews-cognitive-services/) +- [File processing and validation using Azure Functions, Logic Apps, and Durable Functions](https://docs.microsoft.com/samples/azure-samples/serverless-file-validation/file-processing-and-validation-using-azure-functions-logic-apps-and-durable-functions/) - [Implementing a simple Azure Function with a Xamarin.Forms client](https://docs.microsoft.com/samples/azure-samples/functions-xamarin-getting-started/implementing-a-simple-azure-function-with-a-xamarinforms-client/) -- [Lift and shift with serverless Azure functions](https://channel9.msdn.com/Events/Connect/2017/E102) -- [Serverless URL shortener](https://github.com/jeremylikness/serverless-url-shortener) +- [In-editor game telemetry visualization](https://docs.microsoft.com/samples/azure-samples/gaming-in-editor-telemetry/in-editor-telemetry-visualization/) +- [IoT Reliable Edge Relay](https://docs.microsoft.com/samples/azure-samples/iot-reliable-edge-relay/iot-reliable-edge-relay/) +- [Produce and Consume messages through Service Bus, Event Hubs, and Storage Queues with Azure Functions](https://docs.microsoft.com/samples/azure-samples/durable-functions-producer-consumer/product-consume-messages-az-functions/) +- [Run Console Apps on Azure Functions](https://docs.microsoft.com/samples/azure-samples/functions-dotnet-migrating-console-apps/run-console-apps-on-azure-functions/) +- [Serverless functions for GraphQL](https://github.com/softchris/graphql-workshop-dotnet/blob/master/docs/workshop/4.md) +- [Serverless Microservices reference architecture](https://docs.microsoft.com/samples/azure-samples/serverless-microservices-reference-architecture/serverless-microservices-reference-architecture/) >[!div class="step-by-step"] >[Previous](orchestration-patterns.md) diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md index 6a19b2d941433..07ec61f515d94 100644 --- a/docs/core/compatibility/2.2-3.0.md +++ b/docs/core/compatibility/2.2-3.0.md @@ -335,11 +335,16 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, ## Cryptography +- [BEGIN TRUSTED CERTIFICATE syntax no longer supported on Linux](#begin-trusted-certificate-syntax-no-longer-supported-for-root-certificates-on-linux) - [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) - [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) - [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) - [Better argument validation in the Pkcs8PrivateKeyInfo constructor](#better-argument-validation-in-the-pkcs8privatekeyinfo-constructor) +[!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)] + +*** + [!INCLUDE[EnvelopedCms defaults to AES-256 encryption](~/includes/core-changes/cryptography/3.0/envelopedcms-defaults-to-aes256.md)] *** diff --git a/docs/core/compatibility/2.2-3.1.md b/docs/core/compatibility/2.2-3.1.md index edc6d3e19def9..38bef24ac15e0 100644 --- a/docs/core/compatibility/2.2-3.1.md +++ b/docs/core/compatibility/2.2-3.1.md @@ -338,11 +338,16 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core, ## Cryptography +- [BEGIN TRUSTED CERTIFICATE syntax no longer supported on Linux](#begin-trusted-certificate-syntax-no-longer-supported-for-root-certificates-on-linux) - [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) - [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) - [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) - [Better argument validation in the Pkcs8PrivateKeyInfo constructor](#better-argument-validation-in-the-pkcs8privatekeyinfo-constructor) +[!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)] + +*** + [!INCLUDE[EnvelopedCms defaults to AES-256 encryption](~/includes/core-changes/cryptography/3.0/envelopedcms-defaults-to-aes256.md)] *** diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md index 93a555b690e8c..9cdeb94366cce 100644 --- a/docs/core/compatibility/corefx.md +++ b/docs/core/compatibility/corefx.md @@ -29,6 +29,7 @@ The following breaking changes are documented on this page: | [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 | ## .NET Core 3.0 @@ -107,3 +108,7 @@ The following breaking changes are documented on this page: [!INCLUDE [UnauthorizedAccessException thrown by FileSystemInfo.Attributes](~/includes/core-changes/corefx/1.0/filesysteminfo-attributes-exceptions.md)] *** + +[!INCLUDE [corrupted-state-exceptions](~/includes/core-changes/corefx/1.0/corrupted-state-exceptions.md)] + +*** diff --git a/docs/core/compatibility/cryptography.md b/docs/core/compatibility/cryptography.md index 104c5e230a6a9..f8f1e03986073 100644 --- a/docs/core/compatibility/cryptography.md +++ b/docs/core/compatibility/cryptography.md @@ -1,7 +1,7 @@ --- title: Cryptography breaking changes description: Lists cryptography-related breaking changes in .NET Core. -ms.date: 02/10/2020 +ms.date: 04/22/2020 --- # Cryptography breaking changes @@ -9,6 +9,7 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | +| [BEGIN TRUSTED CERTIFICATE syntax no longer supported on Linux](#begin-trusted-certificate-syntax-no-longer-supported-for-root-certificates-on-linux) | 3.0 | | [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) | 3.0 | | [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) | 3.0 | | [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) | 3.0 | @@ -17,6 +18,10 @@ The following breaking changes are documented on this page: ## .NET Core 3.0 +[!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)] + +*** + [!INCLUDE[EnvelopedCms defaults to AES-256 encryption](~/includes/core-changes/cryptography/3.0/envelopedcms-defaults-to-aes256.md)] *** diff --git a/docs/core/compatibility/fx-core.md b/docs/core/compatibility/fx-core.md index c06b3c40ea8ed..d248b65f6a630 100644 --- a/docs/core/compatibility/fx-core.md +++ b/docs/core/compatibility/fx-core.md @@ -15,6 +15,7 @@ If you're migrating an app from .NET Framework to .NET Core, the breaking change - [Change in default value of UseShellExecute](#change-in-default-value-of-useshellexecute) - [UnauthorizedAccessException thrown by FileSystemInfo.Attributes](#unauthorizedaccessexception-thrown-by-filesysteminfoattributes) +- [Handling corrupted-process-state exceptions is not supported](#handling-corrupted-state-exceptions-is-not-supported) ### .NET Core 2.1 @@ -28,6 +29,10 @@ If you're migrating an app from .NET Framework to .NET Core, the breaking change *** +[!INCLUDE [corrupted-state-exceptions](~/includes/core-changes/corefx/1.0/corrupted-state-exceptions.md)] + +*** + ## Cryptography - [Boolean parameter of SignedCms.ComputeSignature is respected](#boolean-parameter-of-signedcmscomputesignature-is-respected) diff --git a/docs/core/porting/index.md b/docs/core/porting/index.md index be519d1fea7a6..63c9bf395ebd5 100644 --- a/docs/core/porting/index.md +++ b/docs/core/porting/index.md @@ -13,35 +13,96 @@ You might have code that currently runs on the .NET Framework that you're intere ## Overview of the porting process +Porting to .NET Core (or .NET Standard) from .NET Framework for many projects is relatively straight forward. 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. + +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. + +## Getting started + +The following tools will be used throughout the process: + +- Visual Studio 2019 +- Download [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) +- _Optional_ Install [dotnet try-convert](https://github.com/dotnet/try-convert) + +## Porting a solution + +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. + +In order to identify the order projects should be migrated, you can use the following tools: + +- [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. + +## Per project steps + We recommend you use the following process when porting your project to .NET Core: +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). + + 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 will make later steps easier by reducing the amount of dependencies you must manage. + +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. + + .NET Core uses a simplified (and different) [project file format](../tools/csproj.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. + + 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. + 1. Retarget all projects you wish to port to target .NET Framework 4.7.2 or higher. This step ensures that you can use API alternatives for .NET Framework-specific targets when .NET Core doesn't support a particular API. -2. Use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to analyze your assemblies and see if they're portable to .NET Core. +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. + +1. Use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to analyze your assemblies and see if they're portable to .NET Core. - The API 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. + 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. -3. 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. + 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. + + There are some cases where APIs are not equivalent and you'll need to do some compiler preprocessor directives (i.e. `#if NET45`) to special case the platforms. At this point, you're 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 is not available in .NET Core. A common way to handle this in code would be something like this: + + ```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 + ``` + +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. 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). -4. 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). +1. At this point, you can switch to targeting .NET Core (generally for applications) or .NET Standard (for libraries). + + 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 funcitonality. 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. + + 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: - 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. + ```xml + net472 + ``` -5. Create new projects for .NET Core and copy over source files, or attempt to convert your existing project file with a tool. + and switch it to the desired framework. For .NET Core 3.1, this would be: - .NET Core uses a simplified (and different) [project file format](../tools/csproj.md) than .NET Framework. You'll need to convert your project files into this format to continue. + ```xml + netcoreapp3.1 + ``` -6. Port your test code. + However, if this is a library that you want to continue supporting .NET Framework specific builds for some reason, you can [multi-target](../../standard/library-guidance/cross-platform-targeting.md) by replacing it with the following: - 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. + ```xml + net472;netstandard2.0 + ``` -Additionally, 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. + If you're using Windows-specific APIs (such as registry access), you should install the [Windows Compatibility Pack](./windows-compat-pack.md). ## Next steps >[!div class="nextstepaction"] >[Analyze dependencies](third-party-deps.md) +>[Package NuGet Package](../deploying/creating-nuget-packages.md) +>[ASP.NET to ASP.NET Core Migration](/aspnet/core/migration/proper-to-2x) diff --git a/docs/core/versions/remove-runtime-sdk-versions.md b/docs/core/versions/remove-runtime-sdk-versions.md index 81e6b8bc90b8e..abeb02155eb71 100644 --- a/docs/core/versions/remove-runtime-sdk-versions.md +++ b/docs/core/versions/remove-runtime-sdk-versions.md @@ -1,7 +1,7 @@ --- title: Remove the .NET Core runtime and SDK description: This article describes how to determine which versions of the .NET Core Runtime and SDK are currently installed, and then, how to remove them on Windows, Mac, and Linux. -ms.date: 12/17/2019 +ms.date: 04/22/2020 author: billwagner ms.author: wiwagn ms.custom: "updateeachrelease" @@ -221,26 +221,30 @@ Note that there's no version attached to `dotnet-host`. If you installed using a tarball, you must remove .NET Core using the manual method. -You remove the SDKs and runtimes separately, by removing the directory that contains that version. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands: +On Linux, you must remove the SDKs and runtimes separately, by removing the versioned directories. To be clear, this deletes the SDK and runtime from disk. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands: ```bash -sudo rm -rf /usr/share/dotnet/sdk/1.0.1 -sudo rm -rf /usr/share/dotnet/shared/Microsoft.NETCore.App/1.0.1 -sudo rm -rf /usr/share/dotnet/shared/Microsoft.AspNetCore.App/1.0.1 -sudo rm -rf /usr/share/dotnet/host/fxr/1.0.1 +version="1.0.1" +sudo rm -rf /usr/local/share/dotnet/sdk/$version +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.NETCore.App/$version +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.All/$version +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/$version +sudo rm -rf /usr/local/share/dotnet/host/fxr/$version ``` The parent directories for the SDK and runtime are listed in the output from the `dotnet --list-sdks` and `dotnet --list-runtimes` command, as shown in the earlier table. # [macOS](#tab/macos) -On Mac, you must remove the SDKs and runtimes separately, by removing the directory that contains that version. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands: +On Mac, you must remove the SDKs and runtimes separately, by removing the versioned directories. To be clear, this deletes the SDK and runtime from disk. For example, to remove the 1.0.1 SDK and runtime, you would use the following bash commands: ```bash -sudo rm -rf /usr/local/share/dotnet/sdk/1.0.1 -sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.NETCore.App/1.0.1 -sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/1.0.1 -sudo rm -rf /usr/local/share/dotnet/host/fxr/1.0.1 +version="1.0.1" +sudo rm -rf /usr/local/share/dotnet/sdk/$version +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.NETCore.App/$version +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.All/$version +sudo rm -rf /usr/local/share/dotnet/shared/Microsoft.AspNetCore.App/$version +sudo rm -rf /usr/local/share/dotnet/host/fxr/$version ``` The parent directories for the SDK and runtime are listed in the output from the `dotnet --list-sdks` and `dotnet --list-runtimes` command, as shown in the earlier table. diff --git a/docs/csharp/language-reference/operators/addition-operator.md b/docs/csharp/language-reference/operators/addition-operator.md index 9774edd615841..e36452463a74b 100644 --- a/docs/csharp/language-reference/operators/addition-operator.md +++ b/docs/csharp/language-reference/operators/addition-operator.md @@ -1,6 +1,6 @@ --- title: "+ and += operators - C# reference" -ms.date: 05/24/2019 +ms.date: 04/23/2020 f1_keywords: - "+_CSharpKeyword" - "+=_CSharpKeyword" @@ -22,7 +22,7 @@ For information about the arithmetic `+` operator, see the [Unary plus and minus ## String concatenation -When one or both operands are of type [string](../builtin-types/reference-types.md#the-string-type), the `+` operator concatenates the string representations of its operands: +When one or both operands are of type [string](../builtin-types/reference-types.md#the-string-type), the `+` operator concatenates the string representations of its operands (the string representation of `null` is an empty string): [!code-csharp-interactive[string concatenation](snippets/AdditionOperator.cs#AddStrings)] diff --git a/docs/csharp/language-reference/operators/nameof.md b/docs/csharp/language-reference/operators/nameof.md index 2fea8e972f63d..9e7a087ebb539 100644 --- a/docs/csharp/language-reference/operators/nameof.md +++ b/docs/csharp/language-reference/operators/nameof.md @@ -1,6 +1,6 @@ --- title: "nameof expression - C# reference" -ms.date: 07/12/2019 +ms.date: 04/23/2020 f1_keywords: - "nameof_CSharpKeyword" - "nameof" @@ -16,6 +16,10 @@ A `nameof` expression produces the name of a variable, type, or member as the st As the preceding example shows, in the case of a type and a namespace, the produced name is usually not [fully qualified](~/_csharplang/spec/basic-concepts.md#fully-qualified-names). +In the case of [verbatim identifiers](../tokens/verbatim.md), the `@` character is not the part of a name, as the following example shows: + +[!code-csharp-interactive[nameof verbatim](snippets/NameOfOperator.cs#Verbatim)] + A `nameof` expression is evaluated at compile time and has no effect at run time. You can use a `nameof` expression to make the argument-checking code more maintainable: diff --git a/docs/csharp/language-reference/operators/snippets/AdditionOperator.cs b/docs/csharp/language-reference/operators/snippets/AdditionOperator.cs index 1f0878a56e1af..db376738bef5b 100644 --- a/docs/csharp/language-reference/operators/snippets/AdditionOperator.cs +++ b/docs/csharp/language-reference/operators/snippets/AdditionOperator.cs @@ -26,9 +26,11 @@ private static void StringConcatenation() // Console.WriteLine("Forgot" + "white space"); Console.WriteLine("Probably the oldest constant: " + Math.PI); + Console.WriteLine(null + "Nothing to add."); // Output: // Forgotwhite space // Probably the oldest constant: 3.14159265358979 + // Nothing to add. // // diff --git a/docs/csharp/language-reference/operators/snippets/NameOfOperator.cs b/docs/csharp/language-reference/operators/snippets/NameOfOperator.cs index a19459769e94f..6de7758a03960 100644 --- a/docs/csharp/language-reference/operators/snippets/NameOfOperator.cs +++ b/docs/csharp/language-reference/operators/snippets/NameOfOperator.cs @@ -18,6 +18,11 @@ public static void Examples() Console.WriteLine(nameof(numbers.Count)); // output: Count Console.WriteLine(nameof(numbers.Add)); // output: Add // + + // + var @new = 5; + Console.WriteLine(nameof(@new)); // output: new + // } private class Person diff --git a/docs/csharp/language-reference/operators/snippets/Program.cs b/docs/csharp/language-reference/operators/snippets/Program.cs index 8b1879f90162d..fc1cb4e9879d1 100644 --- a/docs/csharp/language-reference/operators/snippets/Program.cs +++ b/docs/csharp/language-reference/operators/snippets/Program.cs @@ -103,7 +103,7 @@ static async Task Main(string[] args) UserDefinedConversions.Main(); Console.WriteLine(); - Console.WriteLine("========= switch expression example ========="); + Console.WriteLine("========= switch expression example ============"); SwitchExpressions.Examples(); Console.WriteLine(); diff --git a/docs/csharp/linq/perform-grouped-joins.md b/docs/csharp/linq/perform-grouped-joins.md index 97d85e5b37101..e69792b3d4ee2 100644 --- a/docs/csharp/linq/perform-grouped-joins.md +++ b/docs/csharp/linq/perform-grouped-joins.md @@ -1,7 +1,7 @@ --- title: Perform grouped joins (LINQ in C#) description: Learn how to perform grouped joins using LINQ in C#. -ms.date: 12/01/2016 +ms.date: 04/22/2020 ms.assetid: 9667daf9-a5fd-4b43-a5c4-a9c2b744000e --- # Perform grouped joins @@ -13,6 +13,9 @@ For example, a class or a relational database table named `Student` might contai > [!NOTE] > Each element of the first collection appears in the result set of a group join regardless of whether correlated elements are found in the second collection. In the case where no correlated elements are found, the sequence of correlated elements for that element is empty. The result selector therefore has access to every element of the first collection. This differs from the result selector in a non-group join, which cannot access elements from the first collection that have no match in the second collection. +> [!WARNING] +> has no direct equivalent in traditional relational database terms. However, this method does implement a superset of inner joins and left outer joins. Both of these operations can be written in terms of a grouped join. For more information, see [Join Operations](../programming-guide/concepts/linq/join-operations.md) and [Entity Framework Core, GroupJoin](https://docs.microsoft.com/ef/core/querying/complex-query-operators#groupjoin). + The first example in this article shows you how to perform a group join. The second example shows you how to use a group join to create XML elements. ## Example - Group join diff --git a/docs/csharp/tour-of-csharp/types-and-variables.md b/docs/csharp/tour-of-csharp/types-and-variables.md index d8fa226e78230..161387fd572d3 100644 --- a/docs/csharp/tour-of-csharp/types-and-variables.md +++ b/docs/csharp/tour-of-csharp/types-and-variables.md @@ -78,9 +78,9 @@ C#’s type system is unified such that a value of any type can be treated as an [!code-csharp[Boxing](../../../samples/snippets/csharp/tour/types-and-variables/Program.cs#L1-L10)] -When a value of a value type is converted to type `object`, an `object` instance, also called a "box", is allocated to hold the value, and the value is copied into that box. Conversely, when an `object` reference is cast to a value type, a check is made that the referenced `object` is a box of the correct value type, and, if the check succeeds, the value in the box is copied out. +When a value of a value type is assigned to an `object` reference, a "box" is allocated to hold the value. That box is an instance of a reference type, and the value is copied into that box. Conversely, when an `object` reference is cast to a value type, a check is made that the referenced `object` is a box of the correct value type. If the check succeeds, the value in the box is copied to the value type. -C#’s unified type system effectively means that value types can become objects "on demand." Because of the unification, general-purpose libraries that use type `object` can be used with both reference types and value types. +C#’s unified type system effectively means that value types are treated as `object` references "on demand." Because of the unification, general-purpose libraries that use type `object` can be used with all types that derive from `object`, including both reference types and value types. There are several kinds of *variables* in C#, including fields, array elements, local variables, and parameters. Variables represent storage locations, and every variable has a type that determines what values can be stored in the variable, as shown below. diff --git a/docs/csharp/tutorials/intro-to-csharp/branches-and-loops-local.md b/docs/csharp/tutorials/intro-to-csharp/branches-and-loops-local.md index a489d95525ef9..3bf2b130268b1 100644 --- a/docs/csharp/tutorials/intro-to-csharp/branches-and-loops-local.md +++ b/docs/csharp/tutorials/intro-to-csharp/branches-and-loops-local.md @@ -276,6 +276,42 @@ Experiment with these yourself. Try each of the following: When you're done, let's move on to write some code yourself to use what you've learned. +## Created nested loops + +A `while`, `do` or `for` loop can be nested inside another loop to create a matrix using the combination of each item in the outer loop with each item in the inner loop. Let's do that to build a set of alphanumeric pairs to represent rows and columns. + +One `for` loop can generate the rows: + +```csharp +for (int row = 1; row < 11; row++) +{ + Console.WriteLine($"The row is {row}"); +} +``` + +Another loop can generate the columns: + +```csharp +for (char column = 'a'; column < 'k'; column++) +{ + Console.WriteLine($"The column is {column}"); +} +``` + +You can nest one loop inside the other to form pairs: + +```csharp +for (int row = 1; row < 11; row++) +{ + for (char column = 'a'; column < 'k'; column++) + { + Console.WriteLine($"The cell is ({row}, {column})"); + } +} +``` + +You can see that the outer loop increments once for each full run of the inner loop. Reverse the row and column nesting, and see the changes for yourself. + ## Combine branches and loops Now that you've seen the `if` statement and the looping diff --git a/docs/csharp/tutorials/intro-to-csharp/branches-and-loops.yml b/docs/csharp/tutorials/intro-to-csharp/branches-and-loops.yml index a107753d23efa..93a48cab84e15 100644 --- a/docs/csharp/tutorials/intro-to-csharp/branches-and-loops.yml +++ b/docs/csharp/tutorials/intro-to-csharp/branches-and-loops.yml @@ -237,6 +237,46 @@ items: > [!NOTE] > This online coding experience is in preview mode. If you encounter problems, please report them [on the dotnet/try repo](https://github.com/dotnet/try/issues). +- title: Created nested loops + durationInMinutes: 10 + content: | + A `while`, `do` or `for` loop can be nested inside another loop to create a matrix + using the combination of each item in the outer loop with each item in the inner + loop. Let's do that to build a set of alphanumeric pairs to represent rows and columns. + + One `for` loop can generate the rows: + + ```csharp + for (int row = 1; row < 11; row++) + { + Console.WriteLine($"The row is {row}"); + } + ``` + + Another loop can generate the columns: + + ```csharp + for (char column = 'a'; column < 'k'; column++) + { + Console.WriteLine($"The column is {column}"); + } + ``` + + You can nest one loop inside the other to form pairs: + + ```csharp + for (int row = 1; row < 11; row++) + { + for (char column = 'a'; column < 'k'; column++) + { + Console.WriteLine($"The cell is ({row}, {column})"); + } + } + ``` + + You can see that the outer loop increments once for each full run of the + inner loop. Reverse the row and column nesting, and see the changes for yourself. + - title: Combine branches and loops durationInMinutes: 12 content: | diff --git a/docs/framework/index.yml b/docs/framework/index.yml index e74bf2a37b44d..946f774149d88 100644 --- a/docs/framework/index.yml +++ b/docs/framework/index.yml @@ -12,7 +12,7 @@ metadata: - "f61f02f2-2f20-483d-8f56-a9c8f3a54986" helpviewer_keywords: - ".NET Framework guide" - ms.date: 03/23/2020 + ms.date: 04/22/2020 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | sample | tutorial | video | whats-new @@ -40,6 +40,10 @@ landingContent: # Card - title: Install .NET Framework linkLists: + - linkListType: download + links: + - text: Download the .NET SDK + url: https://dotnet.microsoft.com/download - linkListType: overview links: - text: Installation guide diff --git a/docs/index.yml b/docs/index.yml index df45ed031f812..ca31caeb7d1ba 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -12,7 +12,7 @@ metadata: ms.collection: collection author: BillWagner ms.author: wiwagn - ms.date: 12/19/2019 + ms.date: 04/21/2020 # highlightedContent section (optional) # Maximum of 8 items @@ -20,6 +20,10 @@ highlightedContent: # itemType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new items: # Card + - title: "Download .NET" + itemType: download + url: https://dotnet.microsoft.com/download + # Card - title: "C# introduction. A quick interactive start." itemType: get-started url: csharp/tutorials/intro-to-csharp/hello-world.yml @@ -64,6 +68,12 @@ conceptualContent: - url: core/tutorials/index.md itemType: tutorial text: Tutorials + - url: https://dotnet.microsoft.com/platform/community + itemType: whats-new + text: Community + - url: https://dotnetfoundation.org/ + itemType: overview + text: .NET Foundation # Card - title: .NET concepts summary: Learn the fundamental concepts of .NET @@ -99,7 +109,7 @@ conceptualContent: - url: core/sdk.md itemType: download text: Download the .NET Core SDK - - url: core/tools/index.md + - url: https://dotnet.microsoft.com/download itemType: overview text: .NET Core CLI overview - url: core/porting/index.md diff --git a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md index 47e5962dd0f87..e66e75636fb0b 100644 --- a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md +++ b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md @@ -27,7 +27,7 @@ XML documents can be validated against an XML schema definition language (XSD) s [!code-xml[XSDInference Examples#6](../../../../samples/snippets/xml/VS_Snippets_Data/XSDInference Examples/XML/contosoBooks.xsd#6)] - In the code example that follows, the schema above is added to the property of the object. The object is passed as a parameter to the method of the object, which validates the XML document above. + In the code example that follows, the schema above is added to the property of the object. The object is passed as a parameter to the method of the object, which validates the XML document above. The property of the object is set to `Schema` to enforce validation of the XML document by the method of the object. A is added to the object to handle any or events raised by errors found during the validation process of both the XML document and the schema. diff --git a/docs/standard/index.yml b/docs/standard/index.yml index 960115a0533f1..20d21fb646196 100644 --- a/docs/standard/index.yml +++ b/docs/standard/index.yml @@ -7,7 +7,7 @@ metadata: title: .NET documentation description: Learn about .NET, an open-source developer platform for building many different types of applications. ms.topic: landing-page - ms.date: 03/27/2020 + ms.date: 04/22/2020 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | sample | tutorial | video | whats-new @@ -16,6 +16,10 @@ landingContent: # Card - title: Learn about .NET linkLists: + - linkListType: download + links: + - text: Download the .NET SDK + url: https://dotnet.microsoft.com/download - linkListType: overview links: - text: Tour of .NET diff --git a/docs/standard/memory-and-spans/memory-t-usage-guidelines.md b/docs/standard/memory-and-spans/memory-t-usage-guidelines.md index 20d85060222a5..ac423069b8bf8 100644 --- a/docs/standard/memory-and-spans/memory-t-usage-guidelines.md +++ b/docs/standard/memory-and-spans/memory-t-usage-guidelines.md @@ -330,7 +330,7 @@ public unsafe Task ManagedWrapperAsync(Memory data) private static void MyCompletedCallbackImplementation(IntPtr state, int result) { GCHandle handle = (GCHandle)state; - var actualState = (MyCompletedCallbackState)state; + var actualState = (MyCompletedCallbackState)(handle.Target); handle.Free(); actualState.MemoryHandle.Dispose(); diff --git a/docs/standard/serialization/system-text-json-how-to.md b/docs/standard/serialization/system-text-json-how-to.md index c1024bb383d52..24eb9ea9945e0 100644 --- a/docs/standard/serialization/system-text-json-how-to.md +++ b/docs/standard/serialization/system-text-json-how-to.md @@ -11,12 +11,16 @@ helpviewer_keywords: # How to serialize and deserialize (marshal and unmarshal) JSON in .NET -This article shows how to use the namespace to serialize and deserialize to and from JavaScript Object Notation (JSON). +This article shows how to use the namespace to serialize and deserialize to and from JavaScript Object Notation (JSON). If you're porting existing code from `Newtonsoft.Json`, see [How to migrate to `System.Text.Json`](system-text-json-migrate-from-newtonsoft-how-to.md). The directions and sample code use the library directly, not through a framework such as [ASP.NET Core](/aspnet/core/). Most of the serialization sample code sets to `true` to "pretty-print" the JSON (with indentation and whitespace for human readability). For production use, you would typically accept the default value of `false` for this setting. +The code examples refer to the following class and variants of it: + +[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/WeatherForecast.cs?name=SnippetWF)] + ## Namespaces The namespace contains all the entry points and the main types. The namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. The code examples shown in this article require `using` directives for one or both of these namespaces: diff --git a/docs/visual-basic/index.yml b/docs/visual-basic/index.yml index ba938822248b6..933568fa1540c 100644 --- a/docs/visual-basic/index.yml +++ b/docs/visual-basic/index.yml @@ -7,7 +7,7 @@ metadata: title: "Visual Basic docs - get started, tutorials, reference." description: "Learn Visual Basic programming in .NET - for beginning developers, developers new to Visual Basic, and experienced Visual Basic developers" ms.topic: landing-page # Required - ms.date: 11/27/2019 + ms.date: 04/22/2020 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -17,6 +17,10 @@ landingContent: # Card (optional) - title: Get started linkLists: + - linkListType: download + links: + - text: Download the .NET SDK + url: https://dotnet.microsoft.com/download - linkListType: get-started links: - text: Build a "Hello World" app with .NET Core diff --git a/docs/visual-basic/toc.yml b/docs/visual-basic/toc.yml index 074e4808a8375..1f5ef8ec4d490 100644 --- a/docs/visual-basic/toc.yml +++ b/docs/visual-basic/toc.yml @@ -1414,6 +1414,6 @@ - name: Language Specification href: reference/language-specification/ - name: Sample Applications - href: https://github.com/dotnet/samples/tree/master/snippets/visualbasic + href: https://github.com/dotnet/docs/tree/master/samples/snippets/visualbasic - name: Walkthroughs href: walkthroughs.md diff --git a/docs/whats-new/2019-10.md b/docs/whats-new/2019-10.md index 57e84dd4e081e..7d0b26646fc11 100644 --- a/docs/whats-new/2019-10.md +++ b/docs/whats-new/2019-10.md @@ -198,7 +198,6 @@ The following people have contributed to .NET docs in October 2019. Thank you! Y - [JackTrapper](https://github.com/JackTrapper) - [jgscherber](https://github.com/jgscherber) - Jacob Scherber - [jiimaho](https://github.com/jiimaho) - Jim Aho -- [JohnGaltt](https://github.com/JohnGaltt) - Oleksandr Zholob - [JosephAmalfitanoSSA](https://github.com/JosephAmalfitanoSSA) - Joseph Amalfitano - [KexyBiscuit](https://github.com/KexyBiscuit) - Kexy Biscuit - [kolletzki](https://github.com/kolletzki) - Lukas Kolletzki diff --git a/docs/whats-new/index.yml b/docs/whats-new/index.yml index c5c113b5b622e..82ea9a34e0f3a 100644 --- a/docs/whats-new/index.yml +++ b/docs/whats-new/index.yml @@ -7,7 +7,7 @@ metadata: title: .NET documentation what's new? description: "Learn about new and updated content in .NET docs." ms.topic: landing-page - ms.date: 12/12/2019 + ms.date: 04/22/2020 landingContent: - title: "Find .NET updates" @@ -27,14 +27,16 @@ landingContent: - text: October 2019 url: 2019-10.md - - title: "Get involved - contribute to .NET docs" + - title: "Get involved - contribute" linkLists: - linkListType: overview links: - text: ".NET docs repository" url: https://github.com/dotnet/docs/blob/master/README.md - text: Project structure and labels for issues and pull requests - url: https://github.com/dotnet/docs/blob/master/styleguide/labels-projects.md + url: https://docs.microsoft.com/contribute/dotnet/labels-projects + - text: ".NET Foundation" + url: https://dotnetfoundation.org/ - linkListType: concept links: - text: Microsoft docs contributor guide @@ -45,7 +47,12 @@ landingContent: url: https://github.com/dotnet/dotnet-api-docs/blob/master/CONTRIBUTING.md - text: ".NET samples contributor guide" url: https://github.com/dotnet/samples/blob/master/CONTRIBUTING.md - + - title: "Community" + linkLists: + - linkListType: whats-new + links: + - text: Community + url: https://dotnet.microsoft.com/platform/community - title: "Related what's new pages" linkLists: - linkListType: whats-new diff --git a/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md b/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md index b88e33048ed0d..7a80149f9bdeb 100644 --- a/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md +++ b/includes/core-changes/aspnetcore/3.0/obsolete-apis-removed.md @@ -24,86 +24,86 @@ The following types and members were marked as obsolete for ASP.NET Core 2.1 and **Types** -- Microsoft.AspNetCore.Diagnostics.Views.WelcomePage -- Microsoft.AspNetCore.DiagnosticsViewPage.Views.AttributeValue -- Microsoft.AspNetCore.DiagnosticsViewPage.Views.BaseView -- Microsoft.AspNetCore.DiagnosticsViewPage.Views.HelperResult -- Microsoft.AspNetCore.Mvc.Formatters.Xml.ProblemDetails21Wrapper -- Microsoft.AspNetCore.Mvc.Formatters.Xml.ValidationProblemDetails21Wrapper -- Microsoft.AspNetCore.Mvc.Razor.Compilation.ViewsFeatureProvider -- Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageArgumentBinder -- Microsoft.AspNetCore.Routing.IRouteValuesAddressMetadata -- Microsoft.AspNetCore.Routing.RouteValuesAddressMetadata +- `Microsoft.AspNetCore.Diagnostics.Views.WelcomePage` +- `Microsoft.AspNetCore.DiagnosticsViewPage.Views.AttributeValue` +- `Microsoft.AspNetCore.DiagnosticsViewPage.Views.BaseView` +- `Microsoft.AspNetCore.DiagnosticsViewPage.Views.HelperResult` +- `Microsoft.AspNetCore.Mvc.Formatters.Xml.ProblemDetails21Wrapper` +- `Microsoft.AspNetCore.Mvc.Formatters.Xml.ValidationProblemDetails21Wrapper` +- `Microsoft.AspNetCore.Mvc.Razor.Compilation.ViewsFeatureProvider` +- `Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageArgumentBinder` +- `Microsoft.AspNetCore.Routing.IRouteValuesAddressMetadata` +- `Microsoft.AspNetCore.Routing.RouteValuesAddressMetadata` **Constructors** -- Microsoft.AspNetCore.Cors.Infrastructure.CorsService(Microsoft.Extensions.Options.IOptions{Microsoft.AspNetCore.Cors.Infrastructure.CorsOptions}) -- Microsoft.AspNetCore.Routing.Tree.TreeRouteBuilder(Microsoft.Extensions.Logging.ILoggerFactory,System.Text.Encodings.Web.UrlEncoder,Microsoft.Extensions.ObjectPool.ObjectPool{Microsoft.AspNetCore.Routing.Internal.UriBuildingContext},Microsoft.AspNetCore.Routing.IInlineConstraintResolver) -- Microsoft.AspNetCore.Mvc.Formatters.OutputFormatterCanWriteContext -- Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(Microsoft.Extensions.Options.IOptions{Microsoft.AspNetCore.Mvc.MvcOptions},Microsoft.AspNetCore.Routing.IInlineConstraintResolver,Microsoft.AspNetCore.Mvc.ModelBinding.IModelMetadataProvider) -- Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(Microsoft.Extensions.Options.IOptions{Microsoft.AspNetCore.Mvc.MvcOptions},Microsoft.AspNetCore.Routing.IInlineConstraintResolver,Microsoft.AspNetCore.Mvc.ModelBinding.IModelMetadataProvider,Microsoft.AspNetCore.Mvc.Infrastructure.IActionResultTypeMapper) -- Microsoft.AspNetCore.Mvc.Formatters.FormatFilter(Microsoft.Extensions.Options.IOptions{Microsoft.AspNetCore.Mvc.MvcOptions}) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ArrayModelBinder`1(Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinder +- `Microsoft.AspNetCore.Cors.Infrastructure.CorsService(IOptions{CorsOptions})` +- `Microsoft.AspNetCore.Routing.Tree.TreeRouteBuilder(ILoggerFactory,UrlEncoder,ObjectPool{UriBuildingContext},IInlineConstraintResolver)` +- `Microsoft.AspNetCore.Mvc.Formatters.OutputFormatterCanWriteContext` +- `Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(IOptions{MvcOptions},IInlineConstraintResolver,IModelMetadataProvider)` +- `Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(IOptions{MvcOptions},IInlineConstraintResolver,IModelMetadataProvider,IActionResultTypeMapper)` +- `Microsoft.AspNetCore.Mvc.Formatters.FormatFilter(IOptions{MvcOptions})` +- ``Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ArrayModelBinder`1(IModelBinder)`` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinder` - [Microsoft.AspNetCore.Mvc.ModelBinding.Binders.CollectionModelBinder`1(IModelBinder)](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.modelbinding.binders.collectionmodelbinder-1.-ctor?view=aspnetcore-2.2#Microsoft_AspNetCore_Mvc_ModelBinding_Binders_CollectionModelBinder_1__ctor_Microsoft_AspNetCore_Mvc_ModelBinding_IModelBinder_) - [Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ComplexTypeModelBinder(IDictionary`2)](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.modelbinding.binders.complextypemodelbinder.-ctor?view=aspnetcore-2.2#Microsoft_AspNetCore_Mvc_ModelBinding_Binders_ComplexTypeModelBinder__ctor_System_Collections_Generic_IDictionary_Microsoft_AspNetCore_Mvc_ModelBinding_ModelMetadata_Microsoft_AspNetCore_Mvc_ModelBinding_IModelBinder__) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DictionaryModelBinder`2(Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder,Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DoubleModelBinder(System.Globalization.NumberStyles) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FloatModelBinder(System.Globalization.NumberStyles) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormCollectionModelBinder -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormFileModelBinder -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.HeaderModelBinder -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.KeyValuePairModelBinder`2(Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder,Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinder) -- Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder(System.Type) -- Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(System.Collections.Generic.IEnumerable{System.Object}) -- Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(System.Collections.Generic.IEnumerable{System.Object},System.Collections.Generic.IEnumerable{System.Object}) -- Microsoft.AspNetCore.Mvc.ModelBinding.ModelBinderFactory(Microsoft.AspNetCore.Mvc.ModelBinding.IModelMetadataProvider,Microsoft.Extensions.Options.IOptions{Microsoft.AspNetCore.Mvc.MvcOptions}) -- Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder(Microsoft.AspNetCore.Mvc.ModelBinding.IModelMetadataProvider,Microsoft.AspNetCore.Mvc.ModelBinding.IModelBinderFactory,Microsoft.AspNetCore.Mvc.ModelBinding.Validation.IObjectModelValidator) +- ``Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DictionaryModelBinder`2(IModelBinder,IModelBinder)`` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DoubleModelBinder(System.Globalization.NumberStyles)` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FloatModelBinder(System.Globalization.NumberStyles)` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormCollectionModelBinder` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormFileModelBinder` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.HeaderModelBinder` +- ``Microsoft.AspNetCore.Mvc.ModelBinding.Binders.KeyValuePairModelBinder`2(IModelBinder,IModelBinder)`` +- `Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder(System.Type)` +- `Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(IEnumerable{System.Object})` +- `Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(IEnumerable{System.Object},IEnumerable{System.Object})` +- `Microsoft.AspNetCore.Mvc.ModelBinding.ModelBinderFactory(IModelMetadataProvider,IOptions{MvcOptions})` +- `Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder(IModelMetadataProvider,IModelBinderFactory,IObjectModelValidator)` - [Microsoft.AspNetCore.Mvc.Routing.KnownRouteValueConstraint()](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.routing.knownroutevalueconstraint.-ctor?view=aspnetcore-2.2#Microsoft_AspNetCore_Mvc_Routing_KnownRouteValueConstraint__ctor) -- Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter -- Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(System.Boolean) -- Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(Microsoft.AspNetCore.Mvc.MvcOptions) -- Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter -- Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(System.Boolean) -- Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(Microsoft.AspNetCore.Mvc.MvcOptions) +- `Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter` +- `Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(System.Boolean)` +- `Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(MvcOptions)` +- `Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter` +- `Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(System.Boolean)` +- `Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(MvcOptions)` - [Microsoft.AspNetCore.Mvc.TagHelpers.ImageTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,IUrlHelperFactory)](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.taghelpers.imagetaghelper.-ctor?view=aspnetcore-2.2#Microsoft_AspNetCore_Mvc_TagHelpers_ImageTagHelper__ctor_Microsoft_AspNetCore_Hosting_IHostingEnvironment_Microsoft_Extensions_Caching_Memory_IMemoryCache_System_Text_Encodings_Web_HtmlEncoder_Microsoft_AspNetCore_Mvc_Routing_IUrlHelperFactory_) -- Microsoft.AspNetCore.Mvc.TagHelpers.LinkTagHelper(Microsoft.AspNetCore.Hosting.IHostingEnvironment,Microsoft.Extensions.Caching.Memory.IMemoryCache,System.Text.Encodings.Web.HtmlEncoder,System.Text.Encodings.Web.JavaScriptEncoder,Microsoft.AspNetCore.Mvc.Routing.IUrlHelperFactory) -- Microsoft.AspNetCore.Mvc.TagHelpers.ScriptTagHelper(Microsoft.AspNetCore.Hosting.IHostingEnvironment,Microsoft.Extensions.Caching.Memory.IMemoryCache,System.Text.Encodings.Web.HtmlEncoder,System.Text.Encodings.Web.JavaScriptEncoder,Microsoft.AspNetCore.Mvc.Routing.IUrlHelperFactory) -- Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.RazorPageAdapter(Microsoft.AspNetCore.Mvc.Razor.RazorPageBase) +- `Microsoft.AspNetCore.Mvc.TagHelpers.LinkTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,JavaScriptEncoder,IUrlHelperFactory)` +- `Microsoft.AspNetCore.Mvc.TagHelpers.ScriptTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,JavaScriptEncoder,IUrlHelperFactory)` +- `Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.RazorPageAdapter(RazorPageBase)` **Properties** -- Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieDomain -- Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieName -- Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookiePath -- Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.RequireSsl -- Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.AllowInferringBindingSourceForCollectionTypesAsFromQuery -- Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.SuppressUseValidationProblemDetailsForInvalidModelStateResponses -- Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.CookieName -- Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Domain -- Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Path -- Microsoft.AspNetCore.Mvc.DataAnnotations.MvcDataAnnotationsLocalizationOptions.AllowDataAnnotationsLocalizationForEnumDisplayAttributes -- Microsoft.AspNetCore.Mvc.Formatters.Xml.MvcXmlOptions.AllowRfc7807CompliantProblemDetailsFormat -- Microsoft.AspNetCore.Mvc.MvcOptions.AllowBindingHeaderValuesToNonStringModelTypes -- Microsoft.AspNetCore.Mvc.MvcOptions.AllowCombiningAuthorizeFilters -- Microsoft.AspNetCore.Mvc.MvcOptions.AllowShortCircuitingValidationWhenNoValidatorsArePresent -- Microsoft.AspNetCore.Mvc.MvcOptions.AllowValidatingTopLevelNodes -- Microsoft.AspNetCore.Mvc.MvcOptions.InputFormatterExceptionPolicy -- Microsoft.AspNetCore.Mvc.MvcOptions.SuppressBindingUndefinedValueToEnumType -- Microsoft.AspNetCore.Mvc.MvcViewOptions.AllowRenderingMaxLengthAttribute -- Microsoft.AspNetCore.Mvc.MvcViewOptions.SuppressTempDataAttributePrefix -- Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowAreas -- Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowDefaultHandlingForOptionsRequests -- Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowMappingHeadRequestsToGetHandler +- `Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieDomain` +- `Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieName` +- `Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookiePath` +- `Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.RequireSsl` +- `Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.AllowInferringBindingSourceForCollectionTypesAsFromQuery` +- `Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.SuppressUseValidationProblemDetailsForInvalidModelStateResponses` +- `Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.CookieName` +- `Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Domain` +- `Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Path` +- `Microsoft.AspNetCore.Mvc.DataAnnotations.MvcDataAnnotationsLocalizationOptions.AllowDataAnnotationsLocalizationForEnumDisplayAttributes` +- `Microsoft.AspNetCore.Mvc.Formatters.Xml.MvcXmlOptions.AllowRfc7807CompliantProblemDetailsFormat` +- `Microsoft.AspNetCore.Mvc.MvcOptions.AllowBindingHeaderValuesToNonStringModelTypes` +- `Microsoft.AspNetCore.Mvc.MvcOptions.AllowCombiningAuthorizeFilters` +- `Microsoft.AspNetCore.Mvc.MvcOptions.AllowShortCircuitingValidationWhenNoValidatorsArePresent` +- `Microsoft.AspNetCore.Mvc.MvcOptions.AllowValidatingTopLevelNodes` +- `Microsoft.AspNetCore.Mvc.MvcOptions.InputFormatterExceptionPolicy` +- `Microsoft.AspNetCore.Mvc.MvcOptions.SuppressBindingUndefinedValueToEnumType` +- `Microsoft.AspNetCore.Mvc.MvcViewOptions.AllowRenderingMaxLengthAttribute` +- `Microsoft.AspNetCore.Mvc.MvcViewOptions.SuppressTempDataAttributePrefix` +- `Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowAreas` +- `Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowDefaultHandlingForOptionsRequests` +- `Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowMappingHeadRequestsToGetHandler` **Methods** -- Microsoft.AspNetCore.Mvc.LocalRedirectResult.ExecuteResult(Microsoft.AspNetCore.Mvc.ActionContext) -- Microsoft.AspNetCore.Mvc.RedirectResult.ExecuteResult(Microsoft.AspNetCore.Mvc.ActionContext) -- Microsoft.AspNetCore.Mvc.RedirectToActionResult.ExecuteResult(Microsoft.AspNetCore.Mvc.ActionContext) -- Microsoft.AspNetCore.Mvc.RedirectToPageResult.ExecuteResult(Microsoft.AspNetCore.Mvc.ActionContext) -- Microsoft.AspNetCore.Mvc.RedirectToRouteResult.ExecuteResult(Microsoft.AspNetCore.Mvc.ActionContext) -- Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder.BindModelAsync(Microsoft.AspNetCore.Mvc.ActionContext,Microsoft.AspNetCore.Mvc.ModelBinding.IValueProvider,Microsoft.AspNetCore.Mvc.Abstractions.ParameterDescriptor) +- `Microsoft.AspNetCore.Mvc.LocalRedirectResult.ExecuteResult(ActionContext)` +- `Microsoft.AspNetCore.Mvc.RedirectResult.ExecuteResult(ActionContext)` +- `Microsoft.AspNetCore.Mvc.RedirectToActionResult.ExecuteResult(ActionContext)` +- `Microsoft.AspNetCore.Mvc.RedirectToPageResult.ExecuteResult(ActionContext)` +- `Microsoft.AspNetCore.Mvc.RedirectToRouteResult.ExecuteResult(ActionContext)` +- `Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder.BindModelAsync(ActionContext,IValueProvider,ParameterDescriptor)` - [Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder.BindModelAsync(ActionContext,IValueProvider,ParameterDescriptor,Object)](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.modelbinding.parameterbinder.bindmodelasync?view=aspnetcore-2.2#Microsoft_AspNetCore_Mvc_ModelBinding_ParameterBinder_BindModelAsync_Microsoft_AspNetCore_Mvc_ActionContext_Microsoft_AspNetCore_Mvc_ModelBinding_IValueProvider_Microsoft_AspNetCore_Mvc_Abstractions_ParameterDescriptor_System_Object_) diff --git a/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md b/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md new file mode 100644 index 0000000000000..d3fe3d8338f32 --- /dev/null +++ b/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md @@ -0,0 +1,50 @@ +### "BEGIN TRUSTED CERTIFICATE" syntax no longer supported for root certificates on Linux + +Root certificates on Linux and other Unix-like systems (but not macOS) can be presented in two forms: the standard `BEGIN CERTIFICATE` PEM header, and the OpenSSL-specific `BEGIN TRUSTED CERTIFICATE` PEM header. The latter syntax allows for additional configuration that has caused compatibility issues with .NET Core's class. `BEGIN TRUSTED CERTIFICATE` root certificate contents are no longer loaded by the chain engine starting in .NET Core 3.0. + +#### Change description + +Previously, both the `BEGIN CERTIFICATE` and `BEGIN TRUSTED CERTIFICATE` syntaxes were used to populate the root trust list. If the `BEGIN TRUSTED CERTIFICATE` syntax was used and additional options were specified in the file, may have reported that the chain trust was explicitly disallowed (). However, if the certificate was also specified with the `BEGIN CERTIFICATE` syntax in a previously loaded file, the chain trust was allowed. + +Starting in .NET Core 3.0, `BEGIN TRUSTED CERTIFICATE` contents are no longer read. If the certificate is not also specified via a standard `BEGIN CERTIFICATE` syntax, the reports that the root is not trusted (). + +#### Version introduced + +3.0 + +#### Recommended action + +Most applications are unaffected by this change, but applications that cannot see both root certificate sources because of permissions problems may experience unexpected `UntrustedRoot` errors after upgrading. + +Many Linux distributions (or distros) write root certificates into two locations: a one-certificate-per-file directory, and a one-file concatenation. On some distros, the one-certificate-per-file directory uses the `BEGIN TRUSTED CERTIFICATE` syntax while the file concatenation uses the standard `BEGIN CERTIFICATE` syntax. Ensure that any custom root certificates are added as `BEGIN CERTIFICATE` in at least one of these locations, and that both locations can be read by your application. + +The typical directory is */etc/ssl/certs/* and the typical concatenated file is */etc/ssl/cert.pem*. Use the command `openssl version -d` to determine the platform-specific root, which may differ from */etc/ssl/*. For example, on Ubuntu 18.04, the directory is */usr/lib/ssl/certs/* and the file is */usr/lib/ssl/cert.pem*. However, */usr/lib/ssl/certs/* is a symlink to */etc/ssl/certs/* and */usr/lib/ssl/cert.pem* does not exist. + +```bash +$ openssl version -d +OPENSSLDIR: "/usr/lib/ssl" +$ ls -al /usr/lib/ssl +total 12 +drwxr-xr-x 3 root root 4096 Dec 12 17:10 . +drwxr-xr-x 73 root root 4096 Feb 20 15:18 .. +lrwxrwxrwx 1 root root 14 Mar 27 2018 certs -> /etc/ssl/certs +drwxr-xr-x 2 root root 4096 Dec 12 17:10 misc +lrwxrwxrwx 1 root root 20 Nov 12 16:58 openssl.cnf -> /etc/ssl/openssl.cnf +lrwxrwxrwx 1 root root 16 Mar 27 2018 private -> /etc/ssl/private +``` + +### Category + +Cryptography + +### Affected APIs + +- + +