{"id":15561429,"url":"https://github.com/jeevanjames/inifile","last_synced_at":"2025-04-23T22:41:38.807Z","repository":{"id":33551870,"uuid":"158869612","full_name":"JeevanJames/IniFile","owner":"JeevanJames","description":".NET library to open, modify and save .INI files","archived":false,"fork":false,"pushed_at":"2024-01-05T23:56:42.000Z","size":314,"stargazers_count":24,"open_issues_count":13,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T04:11:45.552Z","etag":null,"topics":["ini","ini-file","ini-parser"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JeevanJames.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-23T19:11:52.000Z","updated_at":"2025-03-19T06:48:43.000Z","dependencies_parsed_at":"2025-03-06T18:43:45.288Z","dependency_job_id":null,"html_url":"https://github.com/JeevanJames/IniFile","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeevanJames%2FIniFile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeevanJames%2FIniFile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeevanJames%2FIniFile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeevanJames%2FIniFile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JeevanJames","download_url":"https://codeload.github.com/JeevanJames/IniFile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250528681,"owners_count":21445511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ini","ini-file","ini-parser"],"created_at":"2024-10-02T16:08:10.278Z","updated_at":"2025-04-23T22:41:38.786Z","avatar_url":"https://github.com/JeevanJames.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IniFile.NET [![Build status](https://img.shields.io/appveyor/ci/JeevanJames/inifile.svg)](https://ci.appveyor.com/project/JeevanJames/inifile/branch/master) [![Test status](https://img.shields.io/appveyor/tests/JeevanJames/inifile.svg)](https://ci.appveyor.com/project/JeevanJames/inifile/branch/master) [![NuGet Version](http://img.shields.io/nuget/v/IniFile.NET.svg?style=flat)](https://www.nuget.org/packages/IniFile.NET/) [![NuGet Downloads](https://img.shields.io/nuget/dt/IniFile.NET.svg)](https://www.nuget.org/packages/IniFile.NET/)\n\nIniFile.NET is a .NET library to open, modify and save .INI files.\n\n1. [Nuget Installation](#nuget-installation)\n1. [Ini object model](#ini-object-model)\n1. [Loading an existing .INI](#loading-an-existing-ini)\n    1. [IniLoadSettings](#iniloadsettings)\n1. [Creating an INI file](#creating-a-ini-file)\n    1. [Comments and blank lines](#comments-and-blank-lines)\n1. [Using properties](#using-properties)\n    1. [Gotcha when using implicitly-typed variables to read property values](#gotcha-when-using-implicitly-typed-variables-to-read-property-values)\n    1. [Boolean properties](#boolean-properties)\n    1. [Date/time properties](#datetime-properties)\n    1. [Enum properties](#enum-properties)\n1. [Saving the INI content](#saving-the-ini-content)\n1. [Global configuration](#global-configuration)\n1. [Formatting the INI content](#formatting-the-ini-content)\n\n## Nuget installation\nInstall using package manager:\n```ps\nPM\u003e Install-Package IniFile.NET\n```\n\nInstall using `dotnet` CLI:\n```sh\n\u003e dotnet add package IniFile.NET\n```\n\n## Ini object model\n![Ini object model](/docs/object-model.png)\n\nThe primary class in this library is the `IniFile.Ini` class and it maintains the structure of an .INI file as an in-memory object model, with objects for sections, properties (key-value pairs), comments and blank lines, allowing it to model the exact structure of a .INI file.\n\nThe `IniFile.Ini` class is a collection of `Section` objects (`IList\u003cSection\u003e`). Each `Section` is additionally a collection of `Property` objects (`IList\u003cProperty\u003e`).\n\nBoth `Section` and `Property` objects contain a collection of minor objects, namely `Comment` and `BlankLine` objects, which are the comments and blank lines that appear before the respective sections and properties.\n\n## Loading an existing .INI\nThe `Ini` class provides several constructor overloads to load .INI data from streams, text readers and files.\n```cs\n// Load INI data from a file\nvar ini = new Ini(\"Settings.ini\");\n```\n\nThe class also provides a static factory method `Load` to create an `Ini` object from a string.\n```cs\nconst iniStr = File.ReadAllText(\"Settings.ini\");\nIni ini = Ini.Load(iniStr);\n```\n\n### `IniLoadSettings`\nAll `Ini` constructors and the `Load` static factory method accept an optional `IniLoadSettings` object to control how the .INI data is loaded and handled.\n\n|Property|Description|Default|\n|--------|-----------|-------|\n|`CaseSensitive`|A `bool` indicating whether the section names and property key names in the INI file are case sensitive.|`false`|\n|`DetectEncoding`|A `bool` indicating whether the character encoding should be automatically detected when the INI file is loaded.|`false`|\n|`Encoding`|The character encoding to use when reading or writing data to the INI file.|`UTF-8`|\n|`IgnoreBlankLines`|A `bool` indicating whether to ignore blank lines when loading the INI file content. Useful if you just want to read from the INI file, but not make changes.|`false`|\n|`IgnoreComments`|A `bool` indicating whether to ignore comments when loading the INI file content. Useful if you just want to read from the INI file, but not make changes.|`false`|\n\n```cs\nvar loadSettings = new IniLoadSettings\n{\n    Encoding = Encoding.Unicode,\n    DetectEncoding = true,\n    CaseSensitive = true\n};\nvar ini = new Ini(stream, loadSettings);\n```\n\n## Creating a INI file\nSince the `Ini` class is a collection of `Section` objects (`IList\u003cSection\u003e`) and each `Section` object is a collection of `Property` objects (`IList\u003cProperty\u003e`), so you can use regular `IList\u003cT\u003e` mechanisms to add, remove and manage sections and properties.\n\nSo, for example, you can create an INI from scratch, using collection initializers, as shown here:\n```cs\nvar ini = new Ini\n{\n    new Section(\"Section Name\")\n    {\n        new Property(\"Property1 Name\", \"A string value\"),\n        new Property(\"Property2 Name\", 10)\n    }\n};\n```\n\nProperties are also name-value pairs, so you can also use the dictionary initializer syntax to create them. So the code above can also look like this:\n```cs\nvar ini = new Ini\n{\n    new Section(\"Section Name\")\n    {\n        [\"Property1 Name\"] = \"A string value\",\n        [\"Property2 Name\"] = 10\n    }\n};\n```\n\nSince they are just regular lists, you can use the regular methods and properties on `IList\u003cT\u003e` to manage sections and properties:\n```cs\n// Get number of sections\nint sectionCount = ini.Count;\n\n// Add a new section\nvar section = new Section(\"New section\");\nini.Add(section);\n\n// foreach over the properties of a section\nforeach (Property property in section)\n{\n    // Your code goes here\n}\n\n// You can also use regular LINQ operations\n\n// Check if there are any properties in a section\nif (section.Any())\n{\n    // Your code goes here\n}\n```\n\n### Comments and blank lines\nAny comments and blank lines appearing before a section or property belong to the respective `Section` or `Property` instance, and are stored in an `Items` property.\n```ini\n; This comment and the following blank line\n; belong to the Connections section.\n\n[Connections]\n\n; The blank line directly above, this comment\n; and this comment belong to the SqlDb property\nSqlDb = Db=Server;User=admin;Pwd=passw0rd1\n```\n\nComments and blank lines are represented by the `Comment` and `BlankLine` classes, respectively.\n\nThe `Items` property is a regular `IList\u003c\u003e` collection, and can contain a mix of `Comment` and `BlankLine` instances.\n```cs\n// Two ways to add a comment to a section.\nsection.AddComment(\"This is a comment\");\nsection.Items.Add(new Comment(\"This is a comment.\"));\n\n// Adding a comment to a property.\nproperty.Items.Add(new Comment(\"No need to specify the ; prefix. It is added automatically\"));\n\n// Two ways to add a blank line to a section\nsection.AddBlankLine();\nsection.Items.Add(new BlankLine());\n\n// Find all comments for a property\nIEnumerable\u003cComment\u003e comments = property.Comments;\nIEnumerable\u003cComment\u003e comments = property.Items.OfType\u003cComment\u003e();\n```\n\n`Section` and `Property` constructors also accept a range of strings to denote comments or blank lines. If the string is `null`, empty or just whitespace, then it is considered a blank line, otherwise it is considered a comment. This code:\n```cs\nvar section = new Section(\"SectionName\", null, \"This is a comment surrounded by blank lines\", null);\n```\nwill generate:\n```ini\n\n; This is a comment surrounded by blank lines\n\n[SectionName]\n```\n\n## Using properties\nINI properties are represented by the `Property` class and are name-value pairs, where the name is a `string` and the value can be a `string`, `bool`, any integral number type (`int`, `byte`, `long`, `ushort`, etc.), any floating-point number type (`float`, `double` and `decimal`) and `DateTime`.\n\n```cs\n// Write a double value to a property\nsection[\"Pi\"] = 3.14d;\n\n// Write a boolean value to a property\nvar property = new Property(\"SendMail\", true);\nsection.Add(property);\n\n// Read a string value from a property\nstring name = section[\"Name\"];\n\n// Read a decimal value from a property\ndecimal price = section[\"Price\"];\n```\n\n### Gotcha when using implicitly-typed variables to read property values\nWhen reading property values, if you use an implicitly-typed variable (using `var`), then you will notice that the variable is of type `PropertyValue`. This is the underlying type used by the framework to allow property values to support multiple types like `string`, `int`, `bool`, etc. It does this by allowing implicit conversions between the `PropertyValue` value and all the allowed types.\n\nHowever, when using `var` to declare the variable, the C# compiler will not know the actual type you intend the property value to be.\n```cs\nvar value = section[\"property-name\"]; // value will be of type PropertyValue\n```\n\nTo get the value as the actual type, explicitly specify the variable type:\n```cs\nint value = section[\"property-name\"]; // value will be of type int\n```\n\nAlternatively, you can explicitly cast the `PropertyValue` value to the expected type:\n```cs\nvar value = (int)section[\"property-value\"]; // value will be of type int\n```\n\n### Boolean properties\nThe IniFile framework can recognize the following string values when reading boolean properties:\n\n|Boolean value|Allowed string values|\n|-------------|---------------------|\n|`true`|`1`, `t`, `y`, `on`, `yes`, `enabled`, `true`|\n|`false`|`0`, `f`, `n`, `off`, `no`, `disabled`, `false`|\n\nWhen writing boolean values, the IniFile framework will use the string values configured in the `Ini.Config.Types.TrueString` and `Ini.Config.Types.FalseString` to write the `true` and `false` values respectively to the output INI file.\n\nBy default, `Ini.Config.Types.TrueString` is configured to `1` and `Ini.Config.Types.FalseString` is configured to `0`. So, the following code:\n```cs\nsection[\"HasDiscount\"] = true;\nsection[\"ValidateParking\"] = false;\n```\nwill generate the following properties in the INI file:\n```ini\nHasDiscount = 1\nValidateParking = 0\n```\n\nYou can assign custom strings to the `Ini.Config.Types.TrueString` and `Ini.Config.Types.FalseString` config properties.\n```cs\nIni.Config.SetBooleanStrings(\"Oui\", \"Non\");\n\n// Or the long way\nIni.Config.Types.TrueString = \"Oui\";\nIni.Config.Types.FalseString = \"Non\";\n```\n\n### Date/time properties\nProperty values can be written as `DateTime` values:\n```cs\nsection[\"Today\"] = DateTime.Now;\n```\n\nThe IniFile framework uses the `Ini.Config.Types.DateFormat` property to control how date values are represented as strings in the INI file. By default, this is defaulted to the system's short date format (`CultureInfo.CurrentCulture.DateTimeFormat.ShortDatePattern`).\n```cs\n// Set date format to US style\nIni.Config.SetDateFormats(dateFormat: \"M/dd/yyyy\");\n\n// Or the long way\nIni.Config.Types.DateFormat = \"M/dd/yyyy\";\n\n// Reset the date format to system default\nIni.Config.SetDateFormats();\n\n// Or the long way\nIni.Config.Types.DateFormat = CultureInfo.CurrentCulture.DateTimeFormat.ShortDatePattern;\n```\n\nWhen reading date values from a property, the framework will try to parse the property string value according to the format specified by the `Ini.Config.Types.DateFormat` config value.\n```cs\nDateTime createdDate = section[\"CreatedDate\"];\n```\n\nIf the date string value in the INI file is a different format from the config, you can use the property's `AsDateTime` method to explicitly specify the format:\n```cs\nDateTime createdDate = section[\"CreatedDate\"].AsDateTime(\"yyyy/MM/dd\");\n```\n\n### Enum properties\nProperty values cannot be directly read or written as enum values.\n\nTo write an enum value to a property, use the enum's `ToString` method to write a string representation of the value.\n```cs\nsection[\"StartDay\"] = DayOfWeek.Monday.ToString();\n```\n\nTo read an enum value, the property provides an `AsEnum\u003cT\u003e` method:\n```cs\nDayOfWeek startDay = section[\"StartDay\"].AsEnum\u003cDayOfWeek\u003e();\n```\n\nEnum values are not case-sensitive.\n\n## Saving the INI content\nThe `Ini` class provides several overloads to save the INI content to streams, text writers and files. All these overloads have synchronous and async versions.\n```cs\n// Synchronous call\nini.SaveTo(@\"Setting.ini\");\n\n// Asynchronous call\nawait ini.SaveToAsync(stream);\n```\n\n## Global configuration\nCertain aspects of the IniFile framework can be configured using the static `Ini.Config` property. This has properties to configure behaviors such as:\n* Whether to allow hash symbols (`#`) to represent comments in addition to the default semi-colon (`;`).\n* The default spacings for various types of INI objects such as sections, properties and comments.\n* How to handle reading and writing of certain types of property values, such as booleans and date/times.\n\nWhile, you can set the configuration properties manually, the `Ini.Config` property also provides a fluent API to configure related sets of configurations:\n```cs\nIni.Config\n    .AllowHashForComments(setAsDefault: true)\n    .SetSectionPaddingDefaults(insideLeft: 1, insideRight: 1)\n    .SetPropertyPaddingDefaults(left: 2)\n    .SetBooleanStrings(trueString: \"YES\", falseString: \"NO\")\n    .SetDateFormats(dateFormat: \"M/dd/yy\");\n```\n\n## Formatting the INI content\nThe `Ini` class retains the exact formatting from the source .INI file content. It provides a `Format` method to correctly format the contents.\n\nBy default, the `Format` method resets the padding for all lines in the INI file.\n```cs\nvar ini = new Ini(iniFilePath);\nini.Format();\nini.SaveTo(iniFilePath);\n```\n\nIn addition, the `Format` method takes an optional `IniFormatOptions` parameter that can specify additional formatting options:\n\n|Option|Description|Default|\n|------|-----------|-------|\n|`EnsureBlankLinesBetweenSections`|If true, a blank line is inserted between each section.|`false`|\n|`EnsureBlankLinesBetweenProperties`|If true, a blank line is inserted between each property.|`false`|\n|`RemoveSuccessiveBlankLines`|If true, any successive blank lines are removed.|`false`|\n\n```cs\nvar ini = new Ini(iniFilePath);\nini.Format(new IniFormatOptions\n{\n    EnsureBlankLinesBetweenSections = true,\n    RemoveSuccessiveBlankLines = true\n});\nini.SaveTo(iniFilePath);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeevanjames%2Finifile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeevanjames%2Finifile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeevanjames%2Finifile/lists"}