Merge main into live

docs/ai/quickstarts/get-started-openai.md

@@ -38,8 +38,38 @@ Get started with OpenAI and [Semantic Kernel](../semantic-kernel-dotnet-overview
 
 :::zone target="docs" pivot="azure-openai"
 
+## Create the Azure OpenAI service
+
+# [Azure Developer CLI](#tab/azd)
+
 [!INCLUDE [deploy-azd](includes/deploy-azd.md)]
 
+# [Azure CLI](#tab/azure-cli)
+
+1. To provision an Azure OpenAI service and model using the Azure CLI, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=cli) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\02-HikerAI` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+# [Azure Portal](#tab/azure-portal)
+
+1. To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\02-HikerAI` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+---
+
 :::zone-end
 
 ## Try the HikerAI sample

docs/ai/quickstarts/includes/clone-sample-repo.md

@@ -5,7 +5,7 @@ ms.date: 07/03/2024
 ms.topic: include
 ---
 
-A GitHub repository is available that contains the sample apps for all of the quickstarts. Clone the repository using the following command:
+Clone the GitHub repository that contains the sample apps for all of the quickstarts:
 
 ```bash
 git clone https://github.com/dotnet/ai-samples.git

docs/ai/quickstarts/includes/deploy-azd.md

@@ -5,17 +5,16 @@ ms.date: 07/03/2024
 ms.topic: include
 ---
 
-## Deploy the Azure resources
+The sample GitHub repository is structured as an Azure Developer CLI (`azd`) template, which `azd` can use to provision the Azure OpenAI service and model for you.
 
-Ensure that you follow the [Prerequisites](#prerequisites) to have access to Azure OpenAI Service as well as the Azure Developer CLI, and then use the following guide to get started with the sample application.
-
-1. Clone the repository: [dotnet/ai-samples](https://github.com/dotnet/ai-samples)
-1. From a terminal or command prompt, navigate to the _src\quickstarts\azure-openai_ directory (on macOS or Linux, replace the '\\' character with a '/').
-1. The following command provisions the Azure OpenAI resources. It might take several minutes to create the Azure OpenAI service and deploy the model.
+1. From a terminal or command prompt, navigate to the _src\quickstarts\azure-openai_ directory of the sample repo.
+1. Run the `azd up` command to provision the Azure OpenAI resources. It might take several minutes to create the Azure OpenAI service and deploy the model.
 
    ```azdeveloper
    azd up
    ```
 
-    > [!NOTE]
-    > If you encounter an error during the `azd up` deployment, visit the [troubleshooting](#troubleshoot) section.
+   `azd` also configures the required user secrets for the sample app, such as the OpenAI access key.
+
+   > [!NOTE]
+   > If you encounter an error during the `azd up` deployment, visit the [troubleshooting](#troubleshoot) section.

docs/ai/quickstarts/quickstart-ai-chat-with-data.md

@@ -36,8 +36,38 @@ Get started with AI development using a .NET 8 console app to connect to an Open
 
 :::zone target="docs" pivot="azure-openai"
 
+## Create the Azure OpenAI service
+
+# [Azure Developer CLI](#tab/azd)
+
 [!INCLUDE [deploy-azd](includes/deploy-azd.md)]
 
+# [Azure CLI](#tab/azure-cli)
+
+1. To provision an Azure OpenAI service and model using the Azure CLI, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=cli) article.
+
+1. From a terminal or command prompt, navigate to the  `src\quickstarts\azure-openai\03-ChattingAboutMyHikes` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+# [Azure Portal](#tab/azure-portal)
+
+1. To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article.
+
+1. From a terminal or command prompt, navigate to the  `src\quickstarts\azure-openai\03-ChattingAboutMyHikes` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+---
+
 :::zone-end
 
 ## Try the hiking chat sample

docs/ai/quickstarts/quickstart-azure-openai-tool.md

@@ -38,8 +38,38 @@ Get started with AI by creating a simple .NET 8 console chat application. The ap
 
 :::zone target="docs" pivot="azure-openai"
 
+## Create the Azure OpenAI service
+
+# [Azure Developer CLI](#tab/azd)
+
 [!INCLUDE [deploy-azd](includes/deploy-azd.md)]
 
+# [Azure CLI](#tab/azure-cli)
+
+1. To provision an Azure OpenAI service and model using the Azure CLI, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=cli) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\04-HikerAIPro` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+# [Azure Portal](#tab/azure-portal)
+
+1. To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\04-HikerAIPro` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+---
+
 :::zone-end
 
 ## Try the the hiker pro sample

docs/ai/quickstarts/quickstart-openai-generate-images.md

@@ -34,8 +34,38 @@ Get started with AI by creating a simple .NET 8 console chat application. The ap
 
 :::zone target="docs" pivot="azure-openai"
 
+## Create the Azure OpenAI service
+
+# [Azure Developer CLI](#tab/azd)
+
 [!INCLUDE [deploy-azd](includes/deploy-azd.md)]
 
+# [Azure CLI](#tab/azure-cli)
+
+1. To provision an Azure OpenAI service and model using the Azure CLI, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=cli) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\05-HikeImages` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+# [Azure Portal](#tab/azure-portal)
+
+1. To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\05-HikeImages` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+
+---
+
 :::zone-end
 
 ## Try the the hiking images sample

docs/ai/quickstarts/quickstart-openai-summarize-text.md

@@ -34,8 +34,40 @@ Get started with AI by creating a simple .NET 8.0 console chat application to su
 
 :::zone target="docs" pivot="azure-openai"
 
+## Create the Azure OpenAI service
+
+# [Azure Developer CLI](#tab/azd)
+
 [!INCLUDE [deploy-azd](includes/deploy-azd.md)]
 
+# [Azure CLI](#tab/azure-cli)
+
+1. To provision an Azure OpenAI service and model using the Azure CLI, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=cli) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\01-HikeBenefitsSummary` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+    ```
+
+# [Azure Portal](#tab/azure-portal)
+
+1. To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article.
+
+1. From a terminal or command prompt, navigate to the `src\quickstarts\azure-openai\01-HikeBenefitsSummary` directory.
+
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+    ```
+
+---
+
 :::zone-end
 
 ## Try the hiking benefits sample

docs/core/compatibility/8.0.md

@@ -45,6 +45,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 | [Backslash mapping in Unix file paths](core-libraries/8.0/file-path-backslash.md)                         | Behavioral change   |
 | [Base64.DecodeFromUtf8 methods ignore whitespace](core-libraries/8.0/decodefromutf8-whitespace.md)        | Behavioral change   |
 | [Boolean-backed enum type support removed](core-libraries/8.0/bool-backed-enum.md)                        | Behavioral change   |
+| [Complex.ToString format changed to `<a; b>`](core-libraries/8.0/complex-format.md)              | Behavioral change   |
 | [Drive's current directory path enumeration](core-libraries/8.0/drive-current-dir-paths.md)              | Behavioral change   |
 | [Enumerable.Sum throws new OverflowException for some inputs](core-libraries/8.0/enumerable-sum.md)       | Behavioral change   |
 | [FileStream writes when pipe is closed](core-libraries/8.0/filestream-disposed-pipe.md)                   | Behavioral change   |

docs/core/compatibility/9.0.md

@@ -28,7 +28,8 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 |------------------------------------------------------------------------------------------|---------------------|--------------------|
 | [Adding a ZipArchiveEntry with CompressionLevel sets ZIP central directory header general-purpose bit flags](core-libraries/9.0/compressionlevel-bits.md) | Behavioral change | Preview 5 |
 | [Altered UnsafeAccessor support for non-open generics](core-libraries/9.0/unsafeaccessor-generics.md) | Behavioral change   | Preview 6          |
-| [API obsoletions with custom diagnostic IDs](core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md) | Source incompatible | Preview 1  |
+| [API obsoletions with custom diagnostic IDs](core-libraries/9.0/obsolete-apis-with-custom-diagnostics.md) | Source incompatible | Preview 16 |
+| [BigInteger maximum length](core-libraries/9.0/biginteger-limit.md) | Source incompatible | Preview 1  |
 | [Creating type of array of System.Void not allowed](core-libraries/9.0/type-instance.md) | Behavioral change   | Preview 1          |
 | [Default `Equals()` and `GetHashCode()` throw for types marked with `InlineArrayAttribute`](core-libraries/9.0/inlinearrayattribute.md) | Behavioral change   | Preview 6          |
 | [Inline array struct size limit is enforced](core-libraries/9.0/inlinearray-size.md) | Behavioral change   | Preview 1          |
@@ -64,6 +65,12 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 | [Terminal logger is default](sdk/9.0/terminal-logger.md)                      | Behavioral change | Preview 1          |
 | [Warning emitted for .NET Standard 1.x](sdk/9.0/netstandard-warning.md)       | Source incompatible | Preview 6        |
 
+## Serialization
+
+| Title                                                                       | Type of change    | Introduced version |
+|-----------------------------------------------------------------------------|-------------------|--------------------|
+| [BinaryFormatter always throws](serialization/9.0/binaryformatter-removal.md) | Behavioral change | Preview 6          |
+
 ## Windows Forms
 
 | Title                                                                                   | Type of change      | Introduced version |

docs/core/compatibility/core-libraries/8.0/complex-format.md

@@ -0,0 +1,38 @@
+---
+title: ".NET 8 breaking change: Complex.ToString format changed to `<a; b>`"
+description: Learn about the .NET 8 breaking change in core .NET libraries where the Complex.ToString() format changed from `(a, b)` to `<a; b>`.
+ms.date: 08/06/2024
+---
+# Complex.ToString format changed to `<a; b>`
+
+To better support formatting values with culture-specific information, the default string representation of complex numbers was changed to avoid using characters that can be used in formatted numeric values. This change affects <xref:System.Numerics.Complex.ToString%2A?displayProperty=nameWithType>, where the value is now formatted as `<a; b>` instead of `(a, b)`. Both *a* and *b* are formatted using the general format specifier ("G") and the conventions of the culture defined by provider&mdash;this hasn't changed.
+
+## Previous behavior
+
+Previously, the string representation of the complex number returned by <xref:System.Numerics.Complex.ToString%2A?displayProperty=nameWithType> displayed the number using its Cartesian coordinates in the form `(a, b)`, where *a* was the real part of the complex number, and *b* was its imaginary part.
+
+## New behavior
+
+Starting in .NET 8, the string representation of the complex number returned by <xref:System.Numerics.Complex.ToString%2A?displayProperty=nameWithType> displays the number using its Cartesian coordinates in the form `<a; b>`, where *a* is the real part of the complex number, and *b* is its imaginary part.
+
+## Version introduced
+
+.NET 8
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The change to use a semicolon enables support of formatting with culture-specific information. It also enables the corresponding need to be able to parse results back out given that it implements <xref:System.Numerics.INumberBase%601>.
+
+The change from parentheses (`( )`) to angle brackets avoids potential collision with numeric formats where negative numbers are formatted as `(x)`. The new behavior is also consistent with the behavior of the `Vector*` types.
+
+## Recommended action
+
+If you need the previous format, you can use a custom string formatting mechanism such as `$"({complex.Real}, {complex.Imaginary})"` to produce a string in that format.
+
+## Affected APIs
+
+- <xref:System.Numerics.Complex.ToString%2A?displayProperty=fullName>

docs/core/compatibility/core-libraries/9.0/biginteger-limit.md

@@ -0,0 +1,43 @@
+---
+title: "Breaking change: BigInteger maximum length"
+description: Learn about the .NET 9 breaking change in core .NET libraries where a maximum length for BigInteger is enforced.
+ms.date: 08/06/2024
+---
+# BigInteger maximum length
+
+.NET 9 enforces a maximum length of <xref:System.Numerics.BigInteger>, which is that it can contain no more than `(2^31) - 1` (approximately 2.14 billion) bits. Such a number represents an almost 256 MB allocation and contains approximately 646.5 million digits. This new limit ensures that all APIs exposed are well behaved and consistent while still allowing numbers that are far beyond most usage scenarios.
+
+## Previous behavior
+
+Previously, you could assign a value with a length up to `Array.MaxLength * 32` bits to a <xref:System.Numerics.BigInteger> variable.
+
+> [!NOTE]
+> Typical machines would hit an <xref:System.OutOfMemoryException> far before this limit could ever be reached.
+
+## New behavior
+
+Starting in .NET 9, <xref:System.Numerics.BigInteger> has a maximum length of `(2^31) - 1` (approximately 2.14 billion) bits. If you attempt to assign a larger value, an <xref:System.OverflowException> is thrown at run time. For example, the following code throws an exception:
+
+```csharp
+BigInteger bigInt = new BigInteger(-1) << int.MaxValue;
+```
+
+## Version introduced
+
+.NET 9 Preview 6
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+<xref:System.Numerics.BigInteger> supports representing integer values of essentially arbitrary length. However, in practice, the length is constrained by limits of the underlying computer, such as available memory or how long it would take to compute a given expression. Additionally, there exist some APIs that fail given inputs that result in a value that's too large. For these reasons, a maximum length is now enforced.
+
+## Recommended action
+
+If your code is affected, decrease the length of value you're assigning to <xref:System.Numerics.BigInteger> or add a length check.
+
+## Affected APIs
+
+- <xref:System.Numerics.BigInteger>

docs/core/compatibility/serialization/9.0/binaryformatter-removal.md

@@ -0,0 +1,48 @@
+---
+title: "Breaking change: In-box BinaryFormatter implementation removed and always throws"
+description: Learn about the .NET 9 breaking change in serialization where the in-box BinaryFormatter implementation was removed and always throws exceptions.
+ms.date: 08/06/2024
+---
+# In-box BinaryFormatter implementation removed and always throws
+
+The "in box" <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> implementation now throws exceptions at run time in all cases. This is the final stage of the [BinaryFormatter obsoletion plan](https://github.com/dotnet/designs/blob/main/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md).
+
+## Previous behavior
+
+You could construct a <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> instance and use it to serialize and deserialize payloads.
+
+## New behavior
+
+Starting in .NET 9, the in-box <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> implementation throws exceptions on use, even with the settings that previously enabled its use. Those settings are also removed.
+
+## Version introduced
+
+.NET 9 Preview 6
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+`BinaryFormatter` is an insecure format and the cause of many security bugs. Removing it from the framework increases the overall safety of .NET.
+
+## Recommended action
+
+If your code uses `BinaryFormatter`, you should select a new serialization format and migrate your code.
+
+If you judge the risk of `BinaryFormatter` acceptable for your use cases and you're committed to using a class that can't be made secure, you'll still be able to use `BinaryFormatter` through a separate, unsupported NuGet package.
+
+For more information, including guidance on alternative serializers, see the [BinaryFormatter migration guide](../../../../standard/serialization/binaryformatter-migration-guide/index.md).
+
+## Affected APIs
+
+- <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter?displayProperty=fullName>
+
+## See also
+
+- [Announcement: BinaryFormatter is being removed in .NET 9](https://github.com/dotnet/runtime/issues/98245)
+- [BinaryFormatter disabled across most project types (.NET 8)](../8.0/binaryformatter-disabled.md)
+- [BinaryFormatter serialization APIs produce compiler errors (.NET 7)](../7.0/binaryformatter-apis-produce-errors.md)
+- [SerializationFormat.Binary is obsolete (.NET 7)](../7.0/serializationformat-binary.md)
+- [BinaryFormatter serialization methods are obsolete (.NET 5)](../5.0/binaryformatter-serialization-obsolete.md)