Gerador de origem de configuração
A partir do .NET 8, foi introduzido um gerador de origem de associação de configuração que intercepta sites de chamada específicos e gera sua funcionalidade. Esse recurso fornece uma AOT (antecipação nativa) e uma maneira amigável de usar o associador de configuração, sem o uso da implementação baseada em reflexão. A reflexão requer a geração dinâmica de código, que não tem suporte em cenários AOT.
Esse recurso é possível com o advento dos interceptores C# que foram introduzidos no C# 12. Os interceptores permitem que o compilador gere código-fonte que intercepta chamadas específicas e as substitui pelo código gerado.
Ativar o gerador de origem de configuração
Para ativar o gerador de origem de configuração, adicione a seguinte propriedade ao arquivo de projeto:
<PropertyGroup>
<EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
</PropertyGroup>
Quando o gerador de origem de configuração está habilitado, o compilador gera um arquivo de origem que contém o código de associação de configuração. A origem gerada intercepta APIs de associação das seguintes classes:
- Microsoft.Extensions.Configuration.ConfigurationBinder
- Microsoft.Extensions.DependencyInjection.OptionsBuilderConfigurationExtensions
- Microsoft.Extensions.DependencyInjection.OptionsConfigurationServiceCollectionExtensions
Em outras palavras, todas as APIs que eventualmente chamam esses vários métodos de associação são interceptadas e substituídas pelo código gerado.
Exemplo de uso
Considere um aplicativo de console .NET configurado para publicar como um aplicativo AOT nativo. O código a seguir demonstra como usar o gerador de origem de configuração para associar definições de configuração:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<RootNamespace>console_binder_gen</RootNamespace>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<PublishAot>true</PublishAot>
<InvariantGlobalization>true</InvariantGlobalization>
<EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Configuration" Version="9.0.1" />
<PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.1" />
</ItemGroup>
</Project>
O arquivo de projeto anterior habilita o gerador de origem de configuração definindo a EnableConfigurationBindingGenerator propriedade como true.
Em seguida, considere o arquivo Program.cs :
using Microsoft.Extensions.Configuration;
var builder = new ConfigurationBuilder()
.AddInMemoryCollection(initialData: [
new("port", "5001"),
new("enabled", "true"),
new("apiUrl", "https://jsonplaceholder.typicode.com/")
]);
var configuration = builder.Build();
var settings = new Settings();
configuration.Bind(settings);
// Write the values to the console.
Console.WriteLine($"Port = {settings.Port}");
Console.WriteLine($"Enabled = {settings.Enabled}");
Console.WriteLine($"API URL = {settings.ApiUrl}");
class Settings
{
public int Port { get; set; }
public bool Enabled { get; set; }
public string? ApiUrl { get; set; }
}
// This will output the following:
// Port = 5001
// Enabled = True
// API URL = https://jsonplaceholder.typicode.com/
O código anterior:
- Instancia uma instância do construtor de configuração.
- Chama AddInMemoryCollection e define três valores de origem de configuração.
- Chamadas Build() para criar a configuração.
- Usa o ConfigurationBinder.Bind método para associar o
Settingsobjeto aos valores de configuração.
Quando o aplicativo é criado, o gerador de origem de configuração intercepta a chamada Bind e gera o código de associação.
Importante
Quando a PublishAot propriedade é definida como true (ou qualquer outro aviso AOT está ativado) e a propriedade é definida como false, o EnabledConfigurationBindingGenerator aviso IL2026 é gerado. Esse aviso indica que os membros atribuídos com RequiresUnreferencedCode podem ser interrompidos ao cortar. Para obter mais informações, consulte IL2026.
Explore o código-fonte gerado
O código a seguir é gerado pelo gerador de origem de configuração para o exemplo anterior:
// <auto-generated/>
#nullable enable annotations
#nullable disable warnings
// Suppress warnings about [Obsolete] member usage in generated code.
#pragma warning disable CS0612, CS0618
namespace System.Runtime.CompilerServices
{
using System;
using System.CodeDom.Compiler;
[GeneratedCode("Microsoft.Extensions.Configuration.Binder.SourceGeneration", "9.0.10.47305")]
[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
file sealed class InterceptsLocationAttribute : Attribute
{
public InterceptsLocationAttribute(int version, string data)
{
}
}
}
namespace Microsoft.Extensions.Configuration.Binder.SourceGeneration
{
using Microsoft.Extensions.Configuration;
using System;
using System.CodeDom.Compiler;
using System.Collections.Generic;
using System.Globalization;
using System.Runtime.CompilerServices;
[GeneratedCode("Microsoft.Extensions.Configuration.Binder.SourceGeneration", "9.0.10.47305")]
file static class BindingExtensions
{
#region IConfiguration extensions.
/// <summary>Attempts to bind the given object instance to configuration values by matching property names against configuration keys recursively.</summary>
[InterceptsLocation(1, "uDIs2gDFz/yEvxOzjNK4jnIBAABQcm9ncmFtLmNz")] // D:\source\WorkerService1\WorkerService1\Program.cs(13,15)
public static void Bind_Settings(this IConfiguration configuration, object? instance)
{
ArgumentNullException.ThrowIfNull(configuration);
if (instance is null)
{
return;
}
var typedObj = (global::Settings)instance;
BindCore(configuration, ref typedObj, defaultValueIfNotFound: false, binderOptions: null);
}
#endregion IConfiguration extensions.
#region Core binding extensions.
private readonly static Lazy<HashSet<string>> s_configKeys_Settings = new(() => new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "Port", "Enabled", "ApiUrl" });
public static void BindCore(IConfiguration configuration, ref global::Settings instance, bool defaultValueIfNotFound, BinderOptions? binderOptions)
{
ValidateConfigurationKeys(typeof(global::Settings), s_configKeys_Settings, configuration, binderOptions);
if (configuration["Port"] is string value0 && !string.IsNullOrEmpty(value0))
{
instance.Port = ParseInt(value0, configuration.GetSection("Port").Path);
}
else if (defaultValueIfNotFound)
{
instance.Port = instance.Port;
}
if (configuration["Enabled"] is string value1 && !string.IsNullOrEmpty(value1))
{
instance.Enabled = ParseBool(value1, configuration.GetSection("Enabled").Path);
}
else if (defaultValueIfNotFound)
{
instance.Enabled = instance.Enabled;
}
if (configuration["ApiUrl"] is string value2)
{
instance.ApiUrl = value2;
}
else if (defaultValueIfNotFound)
{
var currentValue = instance.ApiUrl;
if (currentValue is not null)
{
instance.ApiUrl = currentValue;
}
}
}
/// <summary>If required by the binder options, validates that there are no unknown keys in the input configuration object.</summary>
public static void ValidateConfigurationKeys(Type type, Lazy<HashSet<string>> keys, IConfiguration configuration, BinderOptions? binderOptions)
{
if (binderOptions?.ErrorOnUnknownConfiguration is true)
{
List<string>? temp = null;
foreach (IConfigurationSection section in configuration.GetChildren())
{
if (!keys.Value.Contains(section.Key))
{
(temp ??= new List<string>()).Add($"'{section.Key}'");
}
}
if (temp is not null)
{
throw new InvalidOperationException($"'ErrorOnUnknownConfiguration' was set on the provided BinderOptions, but the following properties were not found on the instance of {type}: {string.Join(", ", temp)}");
}
}
}
public static int ParseInt(string value, string? path)
{
try
{
return int.Parse(value, NumberStyles.Integer, CultureInfo.InvariantCulture);
}
catch (Exception exception)
{
throw new InvalidOperationException($"Failed to convert configuration value at '{path}' to type '{typeof(int)}'.", exception);
}
}
public static bool ParseBool(string value, string? path)
{
try
{
return bool.Parse(value);
}
catch (Exception exception)
{
throw new InvalidOperationException($"Failed to convert configuration value at '{path}' to type '{typeof(bool)}'.", exception);
}
}
#endregion Core binding extensions.
}
}
Observação
Esse código gerado está sujeito a alterações com base na versão do gerador de origem de configuração.
O código gerado contém a BindingExtensions classe, que contém o BindCore método que executa a ligação real. O Bind_Settings método chama o BindCore método e converte a instância no tipo especificado.
Para ver o código gerado, defina o <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> no arquivo de projeto. Isso garante que os arquivos fiquem visíveis para o desenvolvedor para inspeção. Você também pode exibir o código gerado no Gerenciador de Soluções do Visual Studio no nó Microsoft.Extensions.Configuration.Binder.SourceGeneration dos Analisadores de> Dependências>do projeto.
