Merge pull request #34955 from dotnet/main

Merge to Live

Author: Rick-Anderson

aspnetcore/performance/ObjectPool/includes/ObjectPool6.md

@@ -36,7 +36,7 @@ Important `ObjectPool` types and interfaces:
 * <xref:Microsoft.Extensions.ObjectPool.ObjectPool`1> : The basic object pool abstraction. Used to get and return objects.
 * <xref:Microsoft.Extensions.ObjectPool.PooledObjectPolicy%601> : Implement this to customize how an object is created and how it is reset when returned to the pool. This can be passed into an object pool that is construct directly, or
 * <xref:Microsoft.Extensions.ObjectPool.ObjectPoolProvider.Create*> : Acts as a factory for creating object pools.
-* [IResettable](https://source.dot.net/#Microsoft.Extensions.ObjectPool/IResettable.cs,9f0c03a4187b92ca,references) : Automatically resets the object when returned to an object pool.
+* <xref:Microsoft.Extensions.ObjectPool.IResettable>: Automatically resets the object when returned to an object pool.
 
 The ObjectPool can be used in an app in multiple ways:
 

aspnetcore/performance/caching/hybrid.md

@@ -9,35 +9,27 @@ uid: performance/caching/hybrid
 ---
 # HybridCache library in ASP.NET Core
 
-> [!IMPORTANT]
-> `HybridCache` is currently still in preview but will be fully released *after* .NET 9.0 in a future minor release of .NET Extensions.
-
-<!--
-[!INCLUDE[](~/includes/not-latest-version.md)] 
-Uncomment this when 9.0 is the default value in the version selector.
--->
-
 This article explains how to configure and use the `HybridCache` library in an ASP.NET Core app. For an introduction to the library, see [the `HybridCache` section of the Caching overview](xref:performance/caching/overview#hybridcache).
 
 ## Get the library
 
 Install the `Microsoft.Extensions.Caching.Hybrid` package.
 
 ```dotnetcli
-dotnet add package Microsoft.Extensions.Caching.Hybrid --version "9.0.0-preview.7.24406.2"
+dotnet add package Microsoft.Extensions.Caching.Hybrid
 ```
 
 ## Register the service
 
-Add the `HybridCache` service to the [dependency injection (DI)](xref:fundamentals/dependency-injection) container by calling [`AddHybridCache`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/HybridCacheServiceExtensions.cs,2c4a0de52ec7387c):
+Add the `HybridCache` service to the [dependency injection (DI)](xref:fundamentals/dependency-injection) container by calling <xref:Microsoft.Extensions.DependencyInjection.HybridCacheServiceExtensions.AddHybridCache%2A>:
 
 :::code language="csharp" source="~/performance/caching/hybrid/samples/9.x/HCMinimal/Program.cs" id="snippet_noconfig" highlight="7":::
 
 The preceding code registers the `HybridCache` service with default options. The registration API can also configure [options](#options) and [serialization](#serialization).
 
 ## Get and store cache entries
 
-The `HybridCache` service provides a [`GetOrCreateAsync`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,990ceb8b6f2999f7) method with two overloads, taking a key and:
+The `HybridCache` service provides a <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache.GetOrCreateAsync%2A> method with two overloads, taking a key and:
 
 * A factory method.
 * State, and a factory method.
@@ -104,29 +96,26 @@ The alternative overload might reduce some overhead from [captured variables](/d
 
 ### The `SetAsync` method
 
-In many scenarios, `GetOrCreateAsync` is the only API needed. But `HybridCache` also has [`SetAsync`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.cs,ed5c0ddff676c5f2) to store an object in cache without trying to retrieve it first.
+In many scenarios, `GetOrCreateAsync` is the only API needed. But `HybridCache` also has <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache.SetAsync%2A> to store an object in cache without trying to retrieve it first.
 <!--
 Add GetAsync when it's implemented.
 -->
 
 ## Remove cache entries by key
 
-When the underlying data for a cache entry changes before it expires, remove the entry explicitly by calling [`RemoveAsync`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.cs,a1f8d27e085182cc) with the key to the entry. An [overload](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,bc261d181c479a57) lets you specify a collection of key values.
+When the underlying data for a cache entry changes before it expires, remove the entry explicitly by calling <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache.RemoveAsync%2A> with the key to the entry. An overload lets you specify a collection of key values.
 
 When an entry is removed, it is removed from both the primary and secondary caches.
 
 ## Remove cache entries by tag
 
-> [!IMPORTANT]
-> This feature is still under development. If you try to remove entries by tag, you will notice that it doesn't have any effect.
-
 Tags can be used to group cache entries and invalidate them together.
 
 Set tags when calling `GetOrCreateAsync`, as shown in the following example:
 
 :::code language="csharp" source="~/performance/caching/hybrid/samples/9.x/HCMinimal/Program.cs" id="snippet_getorcreateoptions" highlight="7,17":::
 
-Remove all entries for a specified tag by calling [`RemoveByTagAsync`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,c37a54f5e962ab23) with the tag value. An [overload](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,9efbe8770df53e9c) lets you specify a collection of tag values.
+Remove all entries for a specified tag by calling <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache.RemoveByTagAsync%2A> with the tag value. An overload lets you specify a collection of tag values.
 
 When an entry is removed, it is removed from both the primary and secondary caches.
 
@@ -142,8 +131,8 @@ The `GetOrCreateAsync` method can also take a `HybridCacheEntryOptions` object t
 
 For more information about the options, see the source code:
 
-* [HybridCacheOptions](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/HybridCacheOptions.cs,8736f7c41cee28f4) class.
-* [HybridCacheEntryOptions](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCacheEntryOptions.cs,fe35dea42677e2f8) class.
+* <xref:Microsoft.Extensions.Caching.Hybrid.HybridCacheOptions> class.
+* <xref:Microsoft.Extensions.Caching.Hybrid.HybridCacheEntryOptions> class.
 
 ## Limits
 
@@ -154,7 +143,7 @@ The following properties of `HybridCacheOptions` let you configure limits that a
 
 ## Serialization
 
-Use of a secondary, out-of-process cache requires serialization. Serialization is configured as part of registering the `HybridCache` service. Type-specific and general-purpose serializers can be configured via the [`AddSerializer`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/HybridCacheBuilderExtensions.cs,954f74a7592cc282) and [`AddSerializerFactory`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/HybridCacheBuilderExtensions.cs,ba940d95d06485ca) methods, chained from the `AddHybridCache` call. By default, the library
+Use of a secondary, out-of-process cache requires serialization. Serialization is configured as part of registering the `HybridCache` service. Type-specific and general-purpose serializers can be configured via the <xref:Microsoft.Extensions.DependencyInjection.HybridCacheBuilderExtensions.AddSerializer%2A> and <xref:Microsoft.Extensions.DependencyInjection.HybridCacheBuilderExtensions.AddSerializerFactory%2A> methods, chained from the `AddHybridCache` call. By default, the library
 handles `string` and `byte[]` internally, and uses `System.Text.Json` for everything else. `HybridCache` can also use other serializers, such as protobuf or XML.
 
 The following example configures the service to use a type-specific protobuf serializer:
@@ -217,7 +206,7 @@ In such cases, inform `HybridCache` that it's safe to reuse instances by:
 
 ### Avoid `byte[]` allocations
 
-`HybridCache` also provides optional APIs for `IDistributedCache` implementations, to avoid `byte[]` allocations. This feature is implemented by the preview versions of the `Microsoft.Extensions.Caching.StackExchangeRedis` and `Microsoft.Extensions.Caching.SqlServer` packages. For more information, see [IBufferDistributedCache](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/IBufferDistributedCache.cs,df9fb366340929b1)
+`HybridCache` also provides optional APIs for `IDistributedCache` implementations, to avoid `byte[]` allocations. This feature is implemented by the preview versions of the `Microsoft.Extensions.Caching.StackExchangeRedis` and `Microsoft.Extensions.Caching.SqlServer` packages. For more information, see <xref:Microsoft.Extensions.Caching.Distributed.IBufferDistributedCache>.
 Here are the .NET CLI commands to install the packages:
 
 ```dotnetcli
@@ -230,7 +219,7 @@ dotnet add package Microsoft.Extensions.Caching.SqlServer
 
 ## Custom HybridCache implementations
 
-A concrete implementation of the `HybridCache` abstract class is included in the shared framework and is provided via dependency injection. But developers are welcome to provide custom implementations of the API.
+A concrete implementation of the `HybridCache` abstract class is included in the shared framework and is provided via dependency injection. But developers are welcome to provide or consume custom implementations of the API, for example [FusionCache](https://github.com/ZiggyCreatures/FusionCache/blob/main/docs/MicrosoftHybridCache.md).
 
 ## Compatibility
 
@@ -241,4 +230,4 @@ The `HybridCache` library supports older .NET runtimes, down to .NET Framework 4
 For more information about `HybridCache`, see the following resources:
 
 * GitHub issue [dotnet/aspnetcore #54647](https://github.com/dotnet/aspnetcore/issues/54647).
-* [`HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,8c0fe94693d1ac8d)
+* [`HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Abstractions/Hybrid/HybridCache.cs,8c0fe94693d1ac8d)  <!--keep--> 

aspnetcore/performance/caching/hybrid/includes/overview.md

@@ -1,4 +1,4 @@
-The [`HybridCache`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,8c0fe94693d1ac8d) API bridges some gaps in the <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> and <xref:Microsoft.Extensions.Caching.Memory.IMemoryCache> APIs. `HybridCache` is an abstract class with a default implementation that handles most aspects of saving to cache and retrieving from cache.
+The <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache> API bridges some gaps in the <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> and <xref:Microsoft.Extensions.Caching.Memory.IMemoryCache> APIs. `HybridCache` is an abstract class with a default implementation that handles most aspects of saving to cache and retrieving from cache.
 
 ### Features
 
@@ -82,5 +82,5 @@ The `HybridCache` library supports older .NET runtimes, down to .NET Framework 4
 For more information, see the following resources:
 
 * <xref:performance/caching/hybrid>
-* [GitHub issue dotnet/aspnetcore #54647](https://github.com/dotnet/aspnetcore/issues/54647)
-* [`HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,8c0fe94693d1ac8d)
+* [Hybrid Cache API proposal (`dotnet/aspnetcore` #54647)](https://github.com/dotnet/aspnetcore/issues/54647)
+* [`HybridCache` source code](https://source.dot.net/#Microsoft.Extensions.Caching.Abstractions/Hybrid/HybridCache.cs,8c0fe94693d1ac8d) <!--keep-->

aspnetcore/release-notes/aspnetcore-8.0.md

@@ -781,7 +781,7 @@ ASP.NET Core 8 adds new features to authentication and authorization.
 
 ### Identity API endpoints
 
-[`MapIdentityApi<TUser>`](https://source.dot.net/#Microsoft.AspNetCore.Identity/IdentityApiEndpointRouteBuilderExtensions.cs,32) is a new extension method that adds two API endpoints (`/register` and `/login`). The main goal of the `MapIdentityApi` is to make it easy for developers to use ASP.NET Core Identity for authentication in JavaScript-based single page apps (SPA) or Blazor apps. Instead of using the default UI provided by ASP.NET Core Identity, which is based on Razor Pages, MapIdentityApi adds JSON API endpoints that are more suitable for SPA apps and nonbrowser apps. For more information, see [Identity API endpoints](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-4/#identity-api-endpoints).
+[`MapIdentityApi<TUser>`](xref:Microsoft.AspNetCore.Routing.IdentityApiEndpointRouteBuilderExtensions.MapIdentityApi%2A) is a new extension method that adds two API endpoints (`/register` and `/login`). The main goal of the `MapIdentityApi` is to make it easy for developers to use ASP.NET Core Identity for authentication in JavaScript-based single page apps (SPA) or Blazor apps. Instead of using the default UI provided by ASP.NET Core Identity, which is based on Razor Pages, MapIdentityApi adds JSON API endpoints that are more suitable for SPA apps and nonbrowser apps. For more information, see [Identity API endpoints](https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-8-preview-4/#identity-api-endpoints).
 
 ### IAuthorizationRequirementData
 
@@ -957,9 +957,9 @@ Metrics have been added for ASP.NET Core hosting, Kestrel, and SignalR. For more
 
 ### IExceptionHandler
 
-[IExceptionHandler](https://source.dot.net/#Microsoft.AspNetCore.Diagnostics/ExceptionHandler/IExceptionHandler.cs,adae2915ad0c6dc5) is a new interface that gives the developer a callback for handling known exceptions in a central location.
+<xref:Microsoft.AspNetCore.Diagnostics.IExceptionHandler> is a new interface that gives the developer a callback for handling known exceptions in a central location.
 
-`IExceptionHandler` implementations are registered by calling [`IServiceCollection.AddExceptionHandler<T>`](https://source.dot.net/#Microsoft.AspNetCore.Diagnostics/ExceptionHandler/ExceptionHandlerServiceCollectionExtensions.cs,e74aac24e3e2cbc9). Multiple implementations can be added, and they're called in the order registered. If an exception handler handles a request, it can return `true` to stop processing. If an exception isn't handled by any exception handler, then control falls back to the default behavior and options from the middleware.
+`IExceptionHandler` implementations are registered by calling [`IServiceCollection.AddExceptionHandler<T>`](xref:Microsoft.Extensions.DependencyInjection.ExceptionHandlerServiceCollectionExtensions.AddExceptionHandler%2A). Multiple implementations can be added, and they're called in the order registered. If an exception handler handles a request, it can return `true` to stop processing. If an exception isn't handled by any exception handler, then control falls back to the default behavior and options from the middleware.
 
 For more information, see [IExceptionHandler](xref:fundamentals/error-handling#iexceptionhandler).
 

aspnetcore/release-notes/aspnetcore-9/includes/hybrid-cache.md

@@ -9,7 +9,7 @@ ms.date: 05/21/2024
 > [!IMPORTANT]
 > `HybridCache` is currently still in preview but will be fully released *after* .NET 9.0 in a future minor release of .NET Extensions.
 
-The [`HybridCache`](https://source.dot.net/#Microsoft.Extensions.Caching.Hybrid/Runtime/HybridCache.cs,8c0fe94693d1ac8d) API bridges some gaps in the existing <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> and <xref:Microsoft.Extensions.Caching.Memory.IMemoryCache> APIs. It also adds new capabilities, such as:
+The <xref:Microsoft.Extensions.Caching.Hybrid.HybridCache> API bridges some gaps in the existing <xref:Microsoft.Extensions.Caching.Distributed.IDistributedCache> and <xref:Microsoft.Extensions.Caching.Memory.IMemoryCache> APIs. It also adds new capabilities, such as:
 
 * **"Stampede" protection** to prevent parallel fetches of the same work.
 * Configurable serialization.

aspnetcore/release-notes/aspnetcore-9/includes/openAPI_completion.md

@@ -4,7 +4,7 @@ ASP.NET Core's OpenAPI support is now more accessible and user-friendly. The Ope
 
 Recognizing this gap, we have introduced a new completion provider and code fixer. These tools are designed to facilitate the discovery and use of OpenAPI APIs, making it easier for developers to integrate OpenAPI into their projects. The completion provider offers real-time code suggestions, while the code fixer assists in correcting common mistakes and improving API usage. This enhancement is part of our ongoing commitment to improve the developer experience and streamline API-related workflows.
 
-When a user types a statement where an OpenAPI-related API is available, the completion provider displays a recommendation for the API. For example, in the following screenshots, completions for [AddOpenApi](https://source.dot.net/#Microsoft.AspNetCore.OpenApi/Extensions/OpenApiServiceCollectionExtensions.cs,61) and [MapOpenApi](https://source.dot.net/#Microsoft.AspNetCore.OpenApi/Extensions/OpenApiEndpointRouteBuilderExtensions.cs,da6124cfb6e2f8d8) are provided when a user is entering an invocation statement on a supported type, such as [IEndpointConventionBuilder](/dotnet/api/microsoft.aspnetcore.builder.iendpointconventionbuilder):
+When a user types a statement where an OpenAPI-related API is available, the completion provider displays a recommendation for the API. For example, in the following screenshots, completions for <xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi> and <xref:Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions.MapOpenApi> are provided when a user is entering an invocation statement on a supported type, such as <xref:Microsoft.AspNetCore.Builder.IEndpointConventionBuilder>:
 
 <img width="508" alt="OpenAPI completions" src="https://github.com/dotnet/AspNetCore.Docs/assets/1857993/1ed9fcb9-7ab7-4239-b7c8-d323724e7222">
 
@@ -78,7 +78,7 @@ class Todo
 
 ### Support for schema transformers on OpenAPI documents
 
-Built-in OpenAPI support now ships with support for schema transformers that can be used to modify schemas generated by [System.Text.Json](/dotnet/api/system.text.json) and the OpenAPI implementation. Like document and operation transformers, schema transformers can be registered on the [OpenApiOptions](https://source.dot.net/#Microsoft.AspNetCore.OpenApi/Services/OpenApiOptions.cs,c0a8b420f4ce6918) object. For example, the following code sample demonstrates using a schema transformer to add an example to a type's schema.
+Built-in OpenAPI support now ships with support for schema transformers that can be used to modify schemas generated by <xref:System.Text.Json?displayProperty=fullName> and the OpenAPI implementation. Like document and operation transformers, schema transformers can be registered on the <xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions> object. For example, the following code sample demonstrates using a schema transformer to add an example to a type's schema.
 
 ```csharp
 using System.ComponentModel;

aspnetcore/release-notes/aspnetcore-9/includes/opt_out_metrics.md

@@ -4,8 +4,8 @@
 
 HTTP requests to an endpoint can be excluded from metrics by adding metadata. Either:
 
-* Add the [`[DisableHttpMetrics]`](https://source.dot.net/#Microsoft.AspNetCore.Http.Extensions/DisableHttpMetricsAttribute.cs,258cd11ebe5f2ee1) attribute to the Web API controller, SignalR hub or gRPC service.
-* Call [DisableHttpMetrics](https://source.dot.net/#Microsoft.AspNetCore.Http.Extensions/HttpMetricsEndpointConventionBuilderExtensions.cs,7537104878c6f44a) when mapping endpoints in app startup:
+* Add the [`[DisableHttpMetrics]` attribute](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) to the Web API controller, SignalR hub or gRPC service.
+* Call <xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics%2A> when mapping endpoints in app startup:
 
 :::code language="csharp" source="~/release-notes/aspnetcore-9/samples/Metrics/Program.cs" id="snippet_1" highlight="5":::