{"id":24829970,"url":"https://github.com/polarbeardk/miracle.settings","last_synced_at":"2025-10-14T04:30:26.185Z","repository":{"id":60773463,"uuid":"63790023","full_name":"PolarbearDK/Miracle.Settings","owner":"PolarbearDK","description":"Load your application settings into strong typed objects with two lines of code.","archived":false,"fork":false,"pushed_at":"2020-05-25T04:03:46.000Z","size":3629,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-24T19:28:26.488Z","etag":null,"topics":["appsettings","array","dictionaries","list","nested-objects","settings","strong-typed"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PolarbearDK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-20T14:53:09.000Z","updated_at":"2023-11-10T19:28:52.000Z","dependencies_parsed_at":"2022-10-04T15:36:38.198Z","dependency_job_id":null,"html_url":"https://github.com/PolarbearDK/Miracle.Settings","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/PolarbearDK/Miracle.Settings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolarbearDK%2FMiracle.Settings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolarbearDK%2FMiracle.Settings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolarbearDK%2FMiracle.Settings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolarbearDK%2FMiracle.Settings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PolarbearDK","download_url":"https://codeload.github.com/PolarbearDK/Miracle.Settings/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolarbearDK%2FMiracle.Settings/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017942,"owners_count":26086213,"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","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["appsettings","array","dictionaries","list","nested-objects","settings","strong-typed"],"created_at":"2025-01-30T23:40:02.334Z","updated_at":"2025-10-14T04:30:25.588Z","avatar_url":"https://github.com/PolarbearDK.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Miracle.Settings\r\n\r\nLoad application settings into strong typed objects with two lines of code.\r\n\r\n- No need to write code that load, convert and validate each configuration value.\r\n- No \"magic strings\" and no defaults scattered around in source files.\r\n- Loaded models are guaranteed to be valid.\r\n- Get detailed error message on load error, describing exactly which setting has failed.\r\n- Load settings at startup and application fails immediately upon bad configuration (Fail fast).\r\n- Load complex structores like nested objects, arrays, lists and dictionaries.\r\n- Use DI to inject strong typed setting models into application at startup.\r\n- Works with Full .NET and .NET Core.\r\n\r\n## Table of content\r\n\r\n- [Miracle.Settings](#miraclesettings)\r\n  - [Table of content](#table-of-content)\r\n  - [Install](#install)\r\n  - [Usage](#usage)\r\n  - [Nested objects](#nested-objects)\r\n  - [Arrays, Lists \u0026 Dictionaries](#arrays-lists--dictionaries)\r\n- [Advanced topics](#advanced-topics)\r\n\r\n## Install\r\n\r\nAvailable as a NuGet package: [Miracle.Settings](https://www.nuget.org/packages/Miracle.Settings/)\r\n\r\nTo install Miracle.Settings, run the following command in the Package Manager Console\r\n\r\n```Powershell|foo\r\nPM\u003e Install-Package Miracle.Settings\r\n```\r\n\r\n## Usage\r\n\r\nA basic example on how to load settings into a POCO object.\r\n\r\n```XML\r\n\u003cconfiguration\u003e\r\n  \u003cappSettings\u003e\r\n    \u003cadd key=\"Foo\" value=\"Foo string\" /\u003e\r\n    \u003cadd key=\"Bar\" value=\"42\" /\u003e\r\n  \u003c/appSettings\u003e\r\n\u003c/configuration\u003e\r\n```\r\n\r\n```CSharp\r\n// Setting model that appSettings are loaded into\r\npublic class FooBar\r\n{\r\n    public string Foo { get; private set; }\r\n    public int Bar { get; private set; }\r\n}\r\n```\r\n\r\nThe POCO (Plain Old CLR Object) that settings are serialized/loaded into.\r\n\r\n```CSharp\r\nISettingsLoader settingsLoader = new SettingsLoader();\r\n// Get settings at \"root\" level (without a prefix)\r\nvar settings = settingsLoader.Create\u003cFooBar\u003e();\r\n```\r\n\r\nThis code loads settings of type of type FooBar into settings variable.\r\n\r\n**Top Tip!** Load settings ONCE at startup, and expose settings to application using Dependency Injection.\r\n\r\n## Nested objects\r\n\r\nNested objects are supported using property separator (configurable using: SettingLoader.PropertySeparator)\r\n\r\n```XML\r\n\u003cconfiguration\u003e\r\n  \u003cappSettings\u003e\r\n    \u003cadd key=\"MyPrefix:Foo\" value=\"Foo string\" /\u003e\r\n    \u003cadd key=\"MyPrefix:Nested:Foo\" value=\"Foo\" /\u003e\r\n    \u003cadd key=\"MyPrefix:Nested:Bar\" value=\"42\" /\u003e\r\n  \u003c/appSettings\u003e\r\n\u003c/configuration\u003e\r\n```\r\n\r\n```CSharp\r\npublic class FooBar\r\n{\r\n    public string Foo { get; private set; }\r\n    public Nested Nested { get; private set; }\r\n}\r\n\r\npublic class Nested\r\n{\r\n    public string Foo { get; private set; }\r\n    public int Bar { get; private set; }\r\n}\r\n\r\n// Get settings prefixed by \"MyPrefix\"\r\nvar settings = settingsLoader.Create\u003cFooBar\u003e(\"MyPrefix\");\r\n```\r\n\r\n## Arrays, Lists \u0026 Dictionaries\r\n\r\nCollections (Arrays, Lists \u0026 Dictionaries) can be loaded implicitly into setting model properties, or explicitly by calling CreateArray/CreateList/CreateDictionary .\r\n\r\nSimple arrays and lists can be loaded from a single string value containing separated values. See [Controlling settings with annotations](Annotations.md)\r\n\r\nMore advanced scenarios requires a separate value for each collection item. Keys must be unique, so collection keys must be suffixed by something to make them unique.\r\n\r\n```XML\r\n\u003cconfiguration\u003e\r\n  \u003cappSettings\u003e\r\n    \u003cadd key=\"MyPrefix.1\" value=\"Foo string\" /\u003e\r\n    \u003cadd key=\"MyPrefix.2\" value=\"Foo\" /\u003e\r\n    \u003cadd key=\"MyPrefix.x\" value=\"42\" /\u003e\r\n  \u003c/appSettings\u003e\r\n\u003c/configuration\u003e\r\n```\r\n\r\n```CSharp\r\n// Get the same settings as array, list \u0026 dictionary.\r\n\r\n// With array and list, the \"key\" path is lost.\r\nstring[] settings1 = settingsLoader.CreateArray\u003cstring\u003e(\"MyPrefix\");\r\nList\u003cstring\u003e settings2 = settingsLoader.CreateList\u003cstring\u003e(\"MyPrefix\");\r\n\r\n// With dictionary, the part of the key after prefix is used as dictionary key.\r\n// In this case this would produce keys: \"1\",\"2\",\"x\"\r\nDictionary\u003cstring,string\u003e settings3 = settingsLoader.CreateDictionary\u003cstring\u003e(\"MyPrefix\");\r\n```\r\n\r\nElements in Arrays and Lists are returned in the same order as they are returned by the value provider. The AppSettings value proveider returns values in the same order as they are specified.\r\n\r\n# Advanced topics\r\n\r\n- [Controlling settings with annotations](Annotations.md)\r\n- [Type converters](TypeConverters.md)\r\n- [Value providers](ValueProviders.md)\r\n- [Validating settings](Validation.md)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarbeardk%2Fmiracle.settings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolarbeardk%2Fmiracle.settings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarbeardk%2Fmiracle.settings/lists"}