-
Notifications
You must be signed in to change notification settings - Fork 4.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Split library and package Readme (#78888)
* Split library and package Readme * Fix punctuation * Fix lint issues * Automatically include package readme file if existent * Rename README.md to PACKAGE.md * Move PACKAGE.md into source directory * Reinstate examples in README.md * Update contributing guidelines * Update docs/coding-guidelines/libraries-packaging.md Co-authored-by: Viktor Hofer <viktor.hofer@microsoft.com>
- Loading branch information
1 parent
b5da2c6
commit 479d013
Showing
44 changed files
with
424 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
41 changes: 41 additions & 0 deletions
41
src/libraries/Microsoft.Extensions.Configuration.Abstractions/src/PACKAGE.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| ## About | ||
|
|
||
| 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) | ||
|
|
||
| For more information, see the documentation: [Configuration in .NET](https://learn.microsoft.com/dotnet/core/extensions/configuration). | ||
|
|
||
| ## Example | ||
|
|
||
| The example below shows a small code sample using this library and trying out the `ConfigurationKeyName` attribute available since .NET 6: | ||
|
|
||
| ```cs | ||
| public class MyClass | ||
| { | ||
| [ConfigurationKeyName("named_property")] | ||
| public string NamedProperty { get; set; } | ||
| } | ||
| ``` | ||
|
|
||
| Given the simple class above, we can create a dictionary to hold the configuration data and use it as the memory source to build a configuration section: | ||
|
|
||
| ```cs | ||
| var dic = new Dictionary<string, string> | ||
| { | ||
| {"named_property", "value for named property"}, | ||
| }; | ||
|
|
||
| var config = new ConfigurationBuilder() | ||
| .AddInMemoryCollection(dic) | ||
| .Build(); | ||
|
|
||
| var options = config.Get<MyClass>(); | ||
| Console.WriteLine(options.NamedProperty); // returns "value for named property" | ||
| ``` |
4 changes: 2 additions & 2 deletions
4
src/libraries/Microsoft.Extensions.Configuration.Binder/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
83 changes: 83 additions & 0 deletions
83
src/libraries/Microsoft.Extensions.Configuration.Binder/src/PACKAGE.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| ## About | ||
|
|
||
| Provides the functionality to bind an object to data in configuration providers for [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration/). This package enables you to represent the configuration data as strongly-typed classes defined in the application code. To bind a configuration, use the [Microsoft.Extensions.Configuration.ConfigurationBinder.Get](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.configurationbinder.get) extension method on the `IConfiguration` object. To use this package, you also need to install a package for the [configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration#configuration-providers), for example, [Microsoft.Extensions.Configuration.Json](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Json/) for the JSON provider. | ||
|
|
||
| For more information, see the documentation: [Configuration in .NET](https://learn.microsoft.com/dotnet/core/extensions/configuration). | ||
|
|
||
| ## Example | ||
| The following example shows how to bind a JSON configuration section to .NET objects. | ||
|
|
||
| ```cs | ||
| using System; | ||
| using Microsoft.Extensions.Configuration; | ||
|
|
||
| class Settings | ||
| { | ||
| public string Server { get; set; } | ||
| public string Database { get; set; } | ||
| public Endpoint[] Endpoints { get; set; } | ||
| } | ||
|
|
||
| class Endpoint | ||
| { | ||
| public string IPAddress { get; set; } | ||
| public int Port { get; set; } | ||
| } | ||
|
|
||
| class Program | ||
| { | ||
| static void Main() | ||
| { | ||
| // Build a configuration object from JSON file | ||
| IConfiguration config = new ConfigurationBuilder() | ||
| .AddJsonFile("appsettings.json") | ||
| .Build(); | ||
|
|
||
| // Bind a configuration section to an instance of Settings class | ||
| Settings settings = config.GetSection("Settings").Get<Settings>(); | ||
|
|
||
| // Read simple values | ||
| Console.WriteLine($"Server: {settings.Server}"); | ||
| Console.WriteLine($"Database: {settings.Database}"); | ||
|
|
||
| // Read nested objects | ||
| Console.WriteLine("Endpoints: "); | ||
|
|
||
| foreach (Endpoint endpoint in settings.Endpoints) | ||
| { | ||
| Console.WriteLine($"{endpoint.IPAddress}:{endpoint.Port}"); | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| To run this example, include an `appsettings.json` file with the following content in your project: | ||
|
|
||
| ```json | ||
| { | ||
| "Settings": { | ||
| "Server": "example.com", | ||
| "Database": "Northwind", | ||
| "Endpoints": [ | ||
| { | ||
| "IPAddress": "192.168.0.1", | ||
| "Port": "80" | ||
| }, | ||
| { | ||
| "IPAddress": "192.168.10.1", | ||
| "Port": "8080" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You can include a configuration file using a code like this in your `.csproj` file: | ||
|
|
||
| ```xml | ||
| <ItemGroup> | ||
| <Content Include="appsettings.json"> | ||
| <CopyToOutputDirectory>Always</CopyToOutputDirectory> | ||
| </Content> | ||
| </ItemGroup> | ||
| ``` |
4 changes: 2 additions & 2 deletions
4
src/libraries/Microsoft.Extensions.Configuration.CommandLine/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
29 changes: 29 additions & 0 deletions
29
src/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| ## About | ||
|
|
||
| Command line configuration provider implementation for [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration/). This package enables you to read configuration parameters from the command line arguments of your application. You can use [CommandLineConfigurationExtensions.AddCommandLine](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration.commandlineconfigurationextensions.addcommandline) extension method on `IConfigurationBuilder` to add the command line configuration provider to the configuration builder. | ||
|
|
||
| For more information, see the documentation: [Command-line configuration provider](https://learn.microsoft.com/dotnet/core/extensions/configuration-providers#command-line-configuration-provider). | ||
|
|
||
| ## Example | ||
|
|
||
| The following example shows how to read application configuration from the command line. You can use a command like `dotnet run --InputPath "c:\fizz" --OutputPath "c:\buzz"` to run it. | ||
|
|
||
| ```cs | ||
| using System; | ||
| using Microsoft.Extensions.Configuration; | ||
|
|
||
| class Program | ||
| { | ||
| static void Main(string[] args) | ||
| { | ||
| // Build a configuration object from command line | ||
| IConfiguration config = new ConfigurationBuilder() | ||
| .AddCommandLine(args) | ||
| .Build(); | ||
|
|
||
| // Read configuration values | ||
| Console.WriteLine($"InputPath: {config["InputPath"]}"); | ||
| Console.WriteLine($"OutputPath: {config["OutputPath"]}"); | ||
| } | ||
| } | ||
| ``` |
Oops, something went wrong.