{"id":21535,"date":"2018-04-15T16:30:00","date_gmt":"2018-04-15T16:30:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/premier_developer\/?p=21535"},"modified":"2019-02-14T20:18:17","modified_gmt":"2019-02-15T03:18:17","slug":"order-of-precedence-when-configuring-asp-net-core","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/premier-developer\/order-of-precedence-when-configuring-asp-net-core\/","title":{"rendered":"Order of Precedence when Configuring ASP.NET Core"},"content":{"rendered":"<p>In this post, Premier Developer Consultant <a href=\"https:\/\/www.linkedin.com\/in\/randyrpatterson\">Randy Patterson<\/a> introduces the new configuration API for ASP.NET Core and its order of precedence.<\/p>\n<hr \/>\n<p>In previous version of ASP.NET, configuration was primarily handled by the <i>ConfigurationManager<\/i> class. This class typically obtained the user configurable settings from the <i>AppSettings<\/i> section located in the XML file <i>web.config<\/i>. While these limited configuration options have worked well in the past, it poses some challenges in cloud and container environments.<\/p>\n<p><strong>The New Configuration API<\/strong><\/p>\n<p>With the introduction of ASP.NET Core, a new <a href=\"https:\/\/docs.microsoft.com\/en-us\/aspnet\/core\/fundamentals\/configuration\/?tabs=basicconfiguration\">Configuration API<\/a> was introduced that pulls <i>key-value<\/i> pairs from many different sources into a single Configuration collection. This allows you to access your configuration keys using a single collection regardless of where the information was sourced from.<\/p>\n<p>ASP.NET Core includes several providers for loading configuration from a variety of sources including:<\/p>\n<ul>\n<li>JSON Files<\/li>\n<li>XML Files<\/li>\n<li>INI Files<\/li>\n<li>Command-line arguments<\/li>\n<li>Environment variables<\/li>\n<li>In-memory .NET objects<\/li>\n<li>Secret Manager storage<\/li>\n<li>Encrypted in Azure Key Vault<\/li>\n<\/ul>\n<p>Additionally, you can use 3<sup>rd<\/sup> party providers or write your own if these configuration sources do not fit your needs.<\/p>\n<p>The ASP.NET Core configuration API provides you with many choices for sourcing your configuration values used by your Web application. Additionally, you get the benefit of dynamic configuration options like Command Line Arguments and Environment Variables that work well cross-platform and when deployed to cloud or container environments. For Example, Kubernetes will often update the containers\u2019 configuration by setting environments variables allowing the container to update its configuration as the cluster environment changes.<\/p>\n<p><strong>Order of Precedence<\/strong><\/p>\n<p>When ASP.NET Core starts, it loads your configuration providers in the order they are configured. Furthermore, if a configuration source is loaded and the key already exists from a previous file, it overwrites the previous value.<\/p>\n<p><strong><span style=\"color: #0080ff\">The last key loaded wins.<\/span><\/strong><\/p>\n<p>Starting with ASP.Net Core version 2.0, the configuration providers setup is hidden in Program.cs behind the method call <i>CreateDefaultBuilder()<\/i><\/p>\n<blockquote><p><span style=\"font-family: Lucida Sans Typewriter\">public static IWebHost BuildWebHost (string[] args) =&gt; WebHost.CreateDefaultBuilder(args).UseStartup&lt;Startup&gt;().Build();<\/span><\/p><\/blockquote>\n<p>Looking at the <a href=\"https:\/\/github.com\/aspnet\/MetaPackages\/blob\/rel\/2.0.0\/src\/Microsoft.AspNetCore\/WebHost.cs\">WebHost.cs<\/a> file on Github (Open Source is great!) we can see that the order the providers are configured is as follows.<\/p>\n<ol>\n<li>appsettings.json file<\/li>\n<li><a><span style=\"color: #000000\">appsettings.{env.EnvironmentName}.json file<\/span><\/a><\/li>\n<li><span style=\"color: #000000\">The local <a href=\"https:\/\/docs.microsoft.com\/en-us\/aspnet\/core\/security\/app-secrets?tabs=visual-studio#secret-manager\">User Secrets File<\/a> #Only in local development environment<\/span><\/li>\n<li><span style=\"color: #000000\">Environment Variables<\/span><\/li>\n<li><span style=\"color: #000000\">Command Line Arguments<\/span><\/li>\n<\/ol>\n<p>As you can see in the list above, Command Line Arguments are loaded last and, therefore, will always replace keys from previous providers. Lets take a look at details for each of the configuration sources.<\/p>\n<p>1. appsettings.json File<\/p>\n<p>The default location for your configuration settings and as the name suggests, it\u2019s formatted as JSON. This file is loaded first and usually contains the default keys and values<\/p>\n<p>Example appssettings.json<\/p>\n<blockquote><p><span style=\"font-family: Lucida Sans Typewriter\">{<\/span><\/p>\n<p><span style=\"font-family: Lucida Sans Typewriter\">\u00a0\u00a0\u00a0\u00a0 \u201cConnectionString\u201d : \u201cdefault connection string\u201d<\/span><\/p>\n<p><span style=\"font-family: Lucida Sans Typewriter\">}<\/span><\/p><\/blockquote>\n<p>2. appsettings.{env.EnvironmentName}.json File<\/p>\n<p>This file is used to override the keys in appsettings.json with deployment environment specific settings. For Example a file named <i>appsettings.production.json<\/i> would contain values specific to production.<\/p>\n<p>3. User Secrets File<\/p>\n<p>The User Secrets file is a JSON file stored on the local developer\u2019s laptop. This file is unencrypted and stored outside of the solution directory and, therefore, is not checked into source control. The user secrets file is used for local development overrides like connecting to a local database server. These configuration values are only relevant to the local developer. For additional information on User Secrets File see the documentation <a target=\"_blank\" href=\"https:\/\/docs.microsoft.com\/en-us\/aspnet\/core\/security\/app-secrets?tabs=visual-studio#secret-manager\" rel=\"noopener\">here<\/a>.<\/p>\n<p>4. Environment Variables<\/p>\n<p>Environment variables are a cross-platform way of storing configuration values and are available on Windows, Linux and Mac. While running on Windows you probably will not use environment variables often but they are used extensively by container orchestrators like Docker Compose and Kubernetes.<\/p>\n<p>5. Command Line Arguments<\/p>\n<p>Command line arguments allow you to update configuration keys when running your application without modifying any files. Any configuration value can be modified at the command line by using the command line syntax of <i>key=value<\/i>. For example, to change a key of <i>ConnectionString<\/i> at runtime you can pass the string <i>ConnectionString=\u201dMy new connection string\u201d <\/i><\/p>\n<blockquote><p><em><span style=\"font-family: Lucida Sans Typewriter\">dotnet WebApplication11.dll connectionstring=\u201dmy new connection string\u201d<\/span><\/em><\/p><\/blockquote>\n<p>For additional information on configuring you application using command line arguments see the documentation <a target=\"_blank\" href=\"https:\/\/docs.microsoft.com\/en-us\/aspnet\/core\/fundamentals\/configuration\/?tabs=basicconfiguration#commandline-configuration-provider\" rel=\"noopener\">here<\/a>.<\/p>\n<p><strong>Summary<\/strong><\/p>\n<p>The Configuration API provided by ASP.Net Core does a great job of loading configuration information from many different sources and allowing us to write the same code to access those values regardless of it\u2019s source. The default providers and order of precedence was hidden behind the method call <i>WebHost.CreateDefaultBuilder(args)<\/i> and hopefully, this article helps you understand how that process works.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>In this post, Premier Developer Consultant Randy Patterson introduces the new configuration API for ASP.NET Core and its order of precedence. In previous version of ASP.NET, configuration was primarily handled by the ConfigurationManager class. This class typically obtained the user configurable settings from the AppSettings section located in the XML file web.config. While these limited [&hellip;]<\/p>\n","protected":false},"author":582,"featured_media":37840,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[67,61,314,3],"class_list":["post-21535","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-permierdev","tag-asp-net","tag-asp-net-core","tag-randy-patterson","tag-team"],"acf":[],"blog_post_summary":"<p>In this post, Premier Developer Consultant Randy Patterson introduces the new configuration API for ASP.NET Core and its order of precedence. In previous version of ASP.NET, configuration was primarily handled by the ConfigurationManager class. This class typically obtained the user configurable settings from the AppSettings section located in the XML file web.config. While these limited [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/21535","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/users\/582"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/comments?post=21535"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/21535\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media\/37840"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media?parent=21535"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/categories?post=21535"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/tags?post=21535"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}