Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add package readmes #91210

Merged
merged 62 commits into from
Sep 18, 2023
Merged
Changes from 58 commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
5098dde
Add package readmes
ViktorHofer Aug 28, 2023
7aaf419
System.Diagnostics.EventLog
carlossanlop Sep 1, 2023
dc40124
System.Diagnostics.PerformanceCounter
carlossanlop Sep 1, 2023
32c9b03
Add package readme for System.Speech
ericstj Sep 5, 2023
538a3bc
Fill Microsoft.Extensions.Logging.Abstraction doc
tarekgh Sep 5, 2023
3f9bf8e
Fill Microsoft.Extensions.Logging doc
tarekgh Sep 5, 2023
f582265
Fill Microsoft.Extensions.Logging.Console doc
tarekgh Sep 5, 2023
1cc11d4
Fill Microsoft.Extensions.Logging.Debug doc
tarekgh Sep 5, 2023
ceecbc0
Merge remote-tracking branch 'upstream/main' into InSourcePackageReadme
stephentoub Sep 5, 2023
753a352
Add Microsoft.Bcl.Async package.md details
stephentoub Sep 5, 2023
e20281d
Add System.Threading.Channels package.md details
stephentoub Sep 5, 2023
01b831e
Fill Microsoft.Extensions.Primitives doc
tarekgh Sep 5, 2023
a859686
Merge branch 'InSourcePackageReadme' of https://github.com/dotnet/run…
tarekgh Sep 5, 2023
628dd0b
Remove trailing spaces from Speech doc file
tarekgh Sep 5, 2023
a6c50e0
Fill Microsoft.Extensions.Options doc
tarekgh Sep 5, 2023
b642db2
Fill System.Text.Encoding.CodePages doc
tarekgh Sep 6, 2023
e0358bb
Add System.IO.Ports
krwq Sep 6, 2023
6cafb45
Add System.Net.Http.Json README
eiriktsarpalis Sep 6, 2023
9217e37
Readme for WinHttpHandler
antonfirsov Sep 6, 2023
5046b1f
Fill Microsoft.Extensions.Options.ConfigurationExtensions doc
tarekgh Sep 6, 2023
e2442e5
Merge branch 'InSourcePackageReadme' of https://github.com/dotnet/run…
tarekgh Sep 6, 2023
d722555
Update Microsoft.Extensions.Http
CarnaViire Sep 6, 2023
9c1d795
Fill Microsoft.Bcl.TimeProvider doc
tarekgh Sep 6, 2023
43303db
Merge branch 'InSourcePackageReadme' of https://github.com/dotnet/run…
tarekgh Sep 6, 2023
5bfc51c
Add Microsoft.Extensions.Caching.Memory package.md details
jozkee Sep 7, 2023
e420125
Add Microsoft.Extensions.DependencyInjection
steveharter Sep 7, 2023
941ea55
Add Microsoft.Extensions.DependencyInjections.Abstractions
steveharter Sep 7, 2023
7e3b194
Add Microsoft.Extensions.Hosting
steveharter Sep 7, 2023
8621b39
Add Microsoft.Extensions.Hosting.WindowsServices
steveharter Sep 7, 2023
a53318d
Update PACKAGE.md for System.DirectoryServices
buyaa-n Sep 7, 2023
cfac502
Apply suggestions from code review
buyaa-n Sep 7, 2023
c71c61a
Update System.DirectoryServices.AccountManagement PACKAGE.md
buyaa-n Sep 7, 2023
53b5112
Remove extra space
buyaa-n Sep 7, 2023
1f54dd0
space
danmoseley Sep 7, 2023
cbbcedb
Add Microsoft.Extensions.Hosting.Abstractions
steveharter Sep 8, 2023
4cecddb
Update PACKAGE.md
steveharter Sep 8, 2023
e987cd0
Update PACKAGE.md
steveharter Sep 8, 2023
1c9f82b
Update Hosting
steveharter Sep 8, 2023
881a662
Update Hosting
steveharter Sep 8, 2023
5bbb977
Remove unnecessary brackets
buyaa-n Sep 8, 2023
2444a7f
add oledb and odbc
danmoseley Sep 8, 2023
342df48
tweak
danmoseley Sep 8, 2023
b7515e9
Update src/libraries/System.Speech/src/PACKAGE.md
danmoseley Sep 8, 2023
ea34d03
Update src/libraries/Microsoft.Extensions.Http/src/PACKAGE.md
danmoseley Sep 8, 2023
c88b6db
Update src/libraries/System.Speech/src/PACKAGE.md
danmoseley Sep 8, 2023
022599f
Apply suggestions from code review
danmoseley Sep 8, 2023
228cba0
Apply suggestions for System.Diagnostics.EventLog & PerformanceCounter
carlossanlop Sep 11, 2023
b5db5b6
added Bcl.Numerics
michaelgsharp Sep 13, 2023
545dca2
Fill template for Microsoft.Extensions.Configuration & Abstractions
ericstj Sep 16, 2023
c4d3e72
Add Microsoft.Extensions.Configuration.Binder readme.
ericstj Sep 16, 2023
3046549
Remove undocumented P2 package readmes
ViktorHofer Sep 18, 2023
d6f6188
Update Feedback library name markdown style
ViktorHofer Sep 18, 2023
ea036c5
Remove en-US culture from links
ViktorHofer Sep 18, 2023
5b57763
Replace important markdown tag with bold
ViktorHofer Sep 18, 2023
513cf12
MathF PR feedback
ViktorHofer Sep 18, 2023
acad01b
Add System.Management packag readme
ViktorHofer Sep 18, 2023
921d8be
Fix trailing whitespace
ViktorHofer Sep 18, 2023
d1176ac
Add ServiceController package readme
ViktorHofer Sep 18, 2023
52e5715
Clean-up
ViktorHofer Sep 18, 2023
aa53051
More clean-up
ViktorHofer Sep 18, 2023
c387565
ConfigurationManager clean-up
ViktorHofer Sep 18, 2023
ab8419a
Last clean-up
ViktorHofer Sep 18, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions src/libraries/Microsoft.Bcl.AsyncInterfaces/src/PACKAGE.md
Original file line number Diff line number Diff line change
@@ -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).
44 changes: 44 additions & 0 deletions src/libraries/Microsoft.Bcl.Numerics/src/PACKAGE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
## 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

```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).
58 changes: 58 additions & 0 deletions src/libraries/Microsoft.Bcl.TimeProvider/src/PACKAGE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
## 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).
89 changes: 89 additions & 0 deletions src/libraries/Microsoft.Extensions.Caching.Memory/src/PACKAGE.md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Original file line number Diff line number Diff line change
@@ -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).
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
## 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:

- [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)
## Key Features

<!-- The key features of this package -->

For more information, see the documentation: [Configuration in .NET](https://learn.microsoft.com/dotnet/core/extensions/configuration).
* 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

## Example
## 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 -->

The example below shows a small code sample using this library and trying out the `ConfigurationKeyName` attribute available since .NET 6:

@@ -39,3 +43,42 @@ 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).
Loading
Loading