Merge pull request #92224 from dotnet/PackageREADMEsRelease80

[release/8.0] Add package readmes

Author: ViktorHofer

docs/coding-guidelines/libraries-packaging.md

@@ -55,11 +55,47 @@ Packages can include a Markdown Readme file with a short usage documentation. To
 The package Readme is displayed on the package details page on [NuGet gallery](https://nuget.org/). You can include the following content in it:
 
 - A description of the package purpose.
+- A list of package key features
+- A code example that demostrates how to use the package.
 - Information when package should be used. For example, if the library is included in the shared framework in .NET, but needs to be installed via NuGet on .NET Framework, it should be mentioned.
-- Information on how to get started with the package.
-- Links to related documentation.
 - A list of common entry-point types for the package, with links to their API docs under [.NET API Browser](https://learn.microsoft.com/dotnet/api/).
-- A short code example that demostrates the package usage.
+- Links to related documentation.
+- Information about how to provide feedback on the package and contribute to it.
+
+Use the following Markdown template for a package Readme:
+
+```
+## About
+
+<!-- A description of the package and where one can find more documentation -->
+
+## Key Features
+
+<!-- The key features of this package -->
+
+## How to Use
+
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+## Additional Documentation
+
+* [Conceptual documentation](...)
+* [API documentation](...)
+
+## Related Packages
+
+<!-- The related packages associated with this package -->
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+ExamplePackage is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).
+```
 
 For a list of supported Markdown features, see [NuGet documentation](https://learn.microsoft.com/nuget/nuget-org/package-readme-on-nuget-org#supported-markdown-features).
 

src/libraries/Microsoft.Bcl.AsyncInterfaces/src/PACKAGE.md

@@ -0,0 +1,64 @@
+## About
+
+As of C# 8, the C# language has support for producing and consuming asynchronous iterators. The library types in support of those features are available in .NET Core 3.0 and newer as well as in .NET Standard 2.1. This library provides the necessary definitions of those types to support these language features on .NET Framework and on .NET Standard 2.0. This library is not necessary nor recommended when targeting versions of .NET that include the relevant support.
+
+## Key Features
+
+<!-- The key features of this package -->
+
+* Enables the use of C# async iterators on older .NET platforms
+
+## How to Use
+
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
+
+```C#
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+internal static class Program
+{
+    private static async Task Main()
+    {
+        Console.WriteLine("Starting...");
+        await foreach (var value in GetValuesAsync())
+        {
+            Console.WriteLine(value);
+        }
+        Console.WriteLine("Finished!");
+
+        static async IAsyncEnumerable<int> GetValuesAsync()
+        {
+            for (int i = 0; i < 10; i++)
+            {
+                await Task.Delay(TimeSpan.FromSeconds(1));
+                yield return i;
+            }
+        }
+    }
+}
+```
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+The main types provided by this library are:
+
+* `IAsyncEnumerable<T>`
+* `IAsyncEnumerator<T>`
+* `IAsyncDisposable<T>`
+
+## Additional Documentation
+
+<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
+
+* [C# Feature Specification](https://learn.microsoft.com/dotnet/csharp/language-reference/proposals/csharp-8.0/async-streams)
+* [Walkthrough article](https://learn.microsoft.com/archive/msdn-magazine/2019/november/csharp-iterating-with-async-enumerables-in-csharp-8)
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+Microsoft.Bcl.AsyncInterfaces is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).

src/libraries/Microsoft.Bcl.Numerics/src/PACKAGE.md

@@ -0,0 +1,45 @@
+## About
+
+As of .NET Core 2.0 and .NET Standard 2.1, the C# language has support for math (System.MathF) functions with floats. This library provides the necessary definitions of those types to support these language features on .NET Framework and on .NET Standard 2.0. This library is not necessary nor recommended when targeting versions of .NET that include the relevant support.
+
+## Key Features
+
+<!-- The key features of this package -->
+
+* Enables the use of MathF on older .NET platforms
+
+## How to Use
+
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
+
+```C#
+using System;
+
+internal static class Program
+{
+    private static async Task Main()
+    {       
+        Console.WriteLine(MathF.Max(1f, 5f)); // returns 5f
+    }
+}
+```
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+The main types provided by this library are:
+
+* `System.MathF`
+
+## Additional Documentation
+
+<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
+
+* [API documentation](https://learn.microsoft.com/dotnet/api/system.mathf)
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+Microsoft.Bcl.Numerics is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).

src/libraries/Microsoft.Bcl.TimeProvider/src/PACKAGE.md

@@ -0,0 +1,57 @@
+## About
+
+Microsoft.Bcl.TimeProvider provides time abstraction support for apps targeting .NET 7 and earlier, as well as those intended for the .NET Framework. For apps targeting .NET 8 and newer versions, referencing this package is unnecessary, as the types it contains are already included in the .NET 8 and higher platform versions.
+
+## Key Features
+
+* Provides a common abstraction for time-related operations.
+
+## How to Use
+
+```csharp
+using System;
+
+// A class that uses TimeProvider to get the current time in Utc coordinates
+public class UtcClock
+{
+    private readonly TimeProvider _timeProvider;
+
+    // Constructor that takes a TimeProvider as a dependency
+    public Clock(TimeProvider timeProvider)
+    {
+        _timeProvider = timeProvider;
+    }
+
+    // A method that returns the current time as a string
+    public string GetTime()
+    {
+        return _timeProvider.GetLocalNow().ToString("HH:mm:ss");
+    }
+}
+
+// A class that inherits from TimeProvider and overrides the GetLocalNow method
+public class UtcTimeProvider : TimeProvider
+{
+    // Override the GetLocalNow method to always return UTC time
+    public override DateTimeOffset GetLocalNow()
+    {
+        return TimeProvider.System.GetUtcNow();
+    }
+}
+
+```
+
+## Main Types
+
+The main types provided by this library are:
+
+* `TimeProvider`
+* `TimeProviderTaskExtensions`
+
+## Additional Documentation
+
+* [API documentation](https://learn.microsoft.com/dotnet/api/system.timeprovider)
+
+## Feedback & Contributing
+
+Microsoft.Bcl.TimeProvider is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).

src/libraries/Microsoft.Extensions.Caching.Memory/src/PACKAGE.md

@@ -0,0 +1,89 @@
+## About
+
+<!-- A description of the package and where one can find more documentation -->
+
+Provides implementations for local and distributed in-memory cache. It stores and retrieves data in a fast and efficient way.
+
+## Key Features
+
+<!-- The key features of this package -->
+
+* A concrete implementation of the IMemoryCache interface, which represents a local in-memory cache that stores and retrieves data in a fast and efficient way
+* A distributed cache that supports higher scale-out than local cache
+* Expiration and eviction policies for its entries
+* Entry prioritization for when the cache size limit is exceeded and needs to be compacted by entry eviction
+* Track of cache statictics
+
+## How to Use
+
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
+
+Use Microsoft.Extensions.Caching.Memory over System.Runtime.Caching when working with ASP.NET Core as it provides better integration support. For example, IMemoryCache works natively with ASP.NET Core dependency injection.
+
+Local in-memory serialization:
+```csharp
+using Microsoft.Extensions.Caching.Memory;
+
+using MemoryCache cache = new(new MemoryCacheOptions());
+
+object valueToCache = new();
+string key = "key";
+
+using (ICacheEntry entry = cache.CreateEntry(key))
+{
+    // Entries are committed after they are disposed therefore it does not exist yet.
+    Console.WriteLine($"Exists: {cache.TryGetValue(key, out _)}\n");
+
+    entry.Value = valueToCache;
+    entry.SlidingExpiration = TimeSpan.FromSeconds(2);
+}
+
+bool exists = cache.TryGetValue(key, out object? cachedValue);
+Console.WriteLine($"Exists: {exists}" );
+Console.WriteLine($"cachedValue is valueToCache? {object.ReferenceEquals(cachedValue, valueToCache)}\n");
+
+Console.WriteLine("Wait for the sliding expiration...");
+Thread.Sleep(TimeSpan.FromSeconds(2));
+
+Console.WriteLine("Exists: " + cache.TryGetValue(key, out _));
+
+// You can also use the acceleration extensions to set and get entries
+string key2 = "key2";
+object value2 = new();
+
+cache.Set("key2", value2);
+
+object? cachedValue2 = cache.Get(key2);
+Console.WriteLine($"cachedValue2 is value2? {object.ReferenceEquals(cachedValue2, value2)}");
+```
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+The main types provided by this library are:
+
+* `Microsoft.Extensions.Caching.Memory.MemoryCache`
+* `Microsoft.Extensions.Caching.Memory.MemoryCacheOptions`
+* `Microsoft.Extensions.Caching.Distributed.MemoryDistributedCache`
+* `Microsoft.Extensions.Caching.Memory.MemoryDistributedCacheOptions`
+
+## Additional Documentation
+
+<!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
+
+* [Conceptual documentation](https://learn.microsoft.com/dotnet/core/extensions/caching)
+* [Cache in-memory in ASP.NET Core](https://learn.microsoft.com/aspnet/core/performance/caching/memory)
+* [API documentation](https://learn.microsoft.com/dotnet/api/microsoft.extensions.caching.memory)
+
+## Related Packages
+
+<!-- The related packages associated with this package -->
+
+[Microsoft.Extensions.Caching.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Abstractions)
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+Microsoft.Extensions.Caching.Memory is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).

src/libraries/Microsoft.Extensions.Configuration.Abstractions/src/PACKAGE.md

@@ -1,18 +1,21 @@
 ## About
 
+<!-- A description of the package and where one can find more documentation -->
+
 Provides abstractions of key-value pair based configuration. Interfaces defined in this package are implemented by classes in [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration/) and other configuration packages.
 
-Commonly used types:
+## Key Features
+
+<!-- The key features of this package -->
 
-- [Microsoft.Extensions.Configuration.IConfiguration](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.iconfiguration)
-- [Microsoft.Extensions.Configuration.IConfigurationBuilder](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.iconfigurationbuilder)
-- [Microsoft.Extensions.Configuration.IConfigurationProvider](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.iconfigurationprovider)
-- [Microsoft.Extensions.Configuration.IConfigurationRoot](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.iconfigurationroot)
-- [Microsoft.Extensions.Configuration.IConfigurationSection](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.iconfigurationsection)
+* Abstractions for string key-value pair configuration sources and sections
+* Path conventions of keys establishing a heirachy of values
+* Support for multiple configuration sources, aggregating and defining precdence for values
+* Support for reload on change
 
-For more information, see the documentation: [Configuration in .NET](https://learn.microsoft.com/dotnet/core/extensions/configuration).
+## How to Use
 
-## Example
+<!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
 
 The example below shows a small code sample using this library and trying out the `ConfigurationKeyName` attribute available since .NET 6:
 
@@ -39,3 +42,41 @@ var config = new ConfigurationBuilder()
 var options = config.Get<MyClass>();
 Console.WriteLine(options.NamedProperty); // returns "value for named property"
 ```
+
+## Main Types
+
+<!-- The main types provided in this library -->
+
+The main types provided by this library are:
+
+* `Microsoft.Extensions.Configuration.IConfiguration`
+* `Microsoft.Extensions.Configuration.IConfigurationBuilder`
+* `Microsoft.Extensions.Configuration.IConfigurationProvider`
+* `Microsoft.Extensions.Configuration.IConfigurationRoot`
+* `Microsoft.Extensions.Configuration.IConfigurationSection`
+
+## Additional Documentation
+
+<!-- Links to further documentation -->
+
+* [Configuration in .NET](https://learn.microsoft.com/dotnet/core/extensions/configuration)
+* [API documentation](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration)
+
+## Related Packages
+
+<!-- The related packages associated with this package -->
+* [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration)
+* [Microsoft.Extensions.Configuration.Binder](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Binder)
+* [Microsoft.Extensions.Configuration.CommandLine](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.CommandLine)
+* [Microsoft.Extensions.Configuration.EnvironmentVariables](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.EnvironmentVariables)
+* [Microsoft.Extensions.Configuration.FileExtensions](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.FileExtensions)
+* [Microsoft.Extensions.Configuration.Ini](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Ini)
+* [Microsoft.Extensions.Configuration.Json](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Json)
+* [Microsoft.Extensions.Configuration.UserSecrets](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets)
+* [Microsoft.Extensions.Configuration.Xml](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Xml)
+
+## Feedback & Contributing
+
+<!-- How to provide feedback on this package and contribute to it -->
+
+Microsoft.Extensions.Caching.Abstractions is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime).