[API Proposal]: Add writable INI configuration provider

[sharpninja]

Background and motivation

Microsoft.Extensions.Configuration.Ini can currently read INI files through AddIniFile and AddIniStream, but it does not provide a supported way to write changes back to an INI file.

Several applications need to edit INI files that are shared with another program or tool. In those cases, overwriting the whole file from a flattened configuration dictionary is risky because unmanaged sections, unmanaged keys, ordering, and value quoting can be lost. A writable provider should support the familiar IConfiguration shape while preserving existing INI content that the caller does not manage.

The motivating scenario for the prototype is editing Classic VICE-style INI resources, where numeric values are commonly bare and string values may be quoted. The same pattern applies to other INI-backed application settings.

API Proposal

namespace Microsoft.Extensions.Configuration;

public static partial class WritableIniConfigurationExtensions
{
    public static IConfigurationBuilder AddWritableIniFile(
        this IConfigurationBuilder builder,
        string path,
        bool optional = true);
}

namespace Microsoft.Extensions.Configuration.Ini;

public sealed partial class WritableIniConfigurationSource : IConfigurationSource
{
    public required string Path { get; set; }
    public bool Optional { get; set; }
    public IConfigurationProvider Build(IConfigurationBuilder builder);
}

public sealed partial class WritableIniConfigurationProvider : ConfigurationProvider
{
    public WritableIniConfigurationProvider(WritableIniConfigurationSource source);

    public string Path { get; }

    public override void Load();
    public void SetValue(string section, string key, string value, bool? quote = null);
    public void Save();
}

public sealed partial class IniDocument
{
    public IniDocument();

    public IReadOnlyList<string> Sections { get; }

    public static IniDocument Parse(string text);
    public string? Get(string section, string key);
    public void Set(string section, string key, string value, bool? quote = null);
    public bool Remove(string section, string key);
    public IReadOnlyList<(string Key, string Value)> Entries(string section);
    public string ToIniString();
    public override string ToString();
}

IniDocument is included in the prototype as the editable document model used by the provider. It is reasonable for API review to decide whether that type should remain public or become an internal implementation detail behind the provider API.

API Usage

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.Ini;

IConfiguration config = new ConfigurationBuilder()
    .AddWritableIniFile("settings.ini", optional: true)
    .Build();

string? existing = config["C64SC:VICIIModel"];

var source = new WritableIniConfigurationSource
{
    Path = "settings.ini",
    Optional = true,
};

var provider = (WritableIniConfigurationProvider)source.Build(new ConfigurationBuilder());
provider.Load();
provider.SetValue("C64SC", "VICIIModel", "1");
provider.SetValue("C64SC", "WIC64IPAddress", "192.168.0.1", quote: true);
provider.Save();

The provider preserves unmanaged sections and keys while updating caller-managed values. When quote is null, updates preserve the existing entry's quote style; new entries default to bare values.

Direct document usage, if accepted as public API:

IniDocument document = IniDocument.Parse(File.ReadAllText("settings.ini"));
document.Set("C64SC", "VICIIModel", "1");
document.Set("C64SC", "WIC64IPAddress", "192.168.0.1", quote: true);
File.WriteAllText("settings.ini", document.ToIniString());

Alternative Designs

• Add write support to IniConfigurationProvider directly. This would change the shape of the existing provider and may be more disruptive than adding an explicit writable provider.
• Expose only WritableIniConfigurationProvider and keep IniDocument internal. This reduces public API surface but prevents callers from using the lossless document model directly.
• Provide a broader write abstraction for all file-backed configuration providers. That is likely larger than the INI-specific need and would require a wider design discussion.
• Save through IConfigurationRoot or IConfigurationProvider.Set only. This does not give callers a way to express quote preservation or force quoted output for specific values.

Risks

• Public write support needs clear semantics for formatting preservation. The prototype preserves sections, keys, order, and value quoting, but does not preserve comments or blank-line layout on save.
• Adding IniDocument as public API increases the reviewed surface area. If the API review prefers a smaller surface, it can be internalized before the implementation PR proceeds.
• INI syntax is loosely defined. The proposed implementation intentionally follows the existing provider's parsing behavior where possible.
• required string Path follows the prototype but may need adjustment if API review prefers constructor parameters or nullable property patterns consistent with existing configuration sources.

Implementation prototype: #128987

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-configuration
See info in area-owners.md if you want to be subscribed.

[tarekgh]

Thank you for the detailed proposal and prototype!

The scenario of losslessly editing INI files shared with other tools is understandable. However, we have some concerns before moving forward:

1. No existing precedent - Today, none of the built-in configuration providers (JSON, XML, INI, etc.) support writing back to their source. IConfigurationProvider.Set is intentionally in-memory only. Adding write-back to INI would be a first, and we'd want to think carefully about whether this should be a broader pattern across all file-based providers rather than an INI-specific addition.

2. Surface area - The proposal adds both a writable provider and a public IniDocument model, which is a significant API surface for a niche scenario.

3. Demand signal - We'd like to see broader community demand for this capability before committing it to the runtime. If this is primarily needed for a specific application (VICE-style INI resources), a standalone NuGet package outside the runtime may be a better fit, at least initially.

We'd recommend publishing this as a community NuGet package first. If it gains traction and we see demand from multiple scenarios, we'd be happy to reconsider bringing it into the platform. That approach also gives more flexibility on the API shape without the constraints of runtime API review.

[sharpninja]

No existing precedent - Today, none of the built-in configuration providers (JSON, XML, INI, etc.) support writing back to their source.

I would be happy to accept that as a challenge. 😎 I have implemented IConfiguration write-thru on several projects.

Surface area - The proposal adds both a writable provider and a public IniDocument model, which is a significant API surface for a niche scenario.

Perhaps a solution based on a new IConfigurationWriter common API that would allow for IIniDocumentWriter, IXmlDocumentWriter, etc. to be defined and standard implementations created that would handle the semantics of the standard config file types?

[svick]

I would be happy to accept that as a challenge. 😎 I have implemented IConfiguration write-thru on several projects.

Keep in mind that implementing it is not the biggest hurdle. Getting an agreement that this is something we want to do and then on what the best design is are (though a prototype implementation can help with the second part).

[rosebyte]

@sharpninja, thank you for the proposal, my concern here is the writing part. We don't implement it in general because it opens a whole set of risks and edge cases:

• what if the file doesn't exist?
• what if it's used by another process?
• what if it's too large for IO to digest?
• what if it was edited the same time by another process/thread/whoever?
• what if the file was renamed?
• how it plays with filesystem watcher?
  ... and I could continue, unfortunately, for a long time.

The recommended approach is - if you want to change something in the configuration and have both the file and its inmemory representation in sync, just edit the file and let filesystem watcher to initiate an update and propagate the changes into memory.

[rosebyte]

I agree with @tarekgh's recommendation - this might be a nice community package for a selected subclass of all possible use-cases. You propose implementing all the moving parts anyway, the source, the provider and the extension method so I dare say you already have all you need in your hand.