Umbraco 9 Beta - appsettings.json config options

chris-evansnz commented 3 years ago

What type of issue is it?

Missing documentation

What article/section is this about?

The appsettings.json configuration file in the Umbraco 9 beta

Describe the issue

The alpha builds of Umbraco 9 / unicore had verbose appsettings.json files, showing various different config options that were available to set, as follows:

{
  "ConnectionStrings": {
    "umbracoDbDSN": ""
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning"
      }
    }
  },
  "Umbraco": {
    "CMS": {
      "Content": {
        "Notifications": {
          "Email": "your@email.here"
        },
        "MacroErrors": "throw"
      },
      "Global": {
        "DefaultUILanguage": "en-us",
        "HideTopLevelNodeFromPath": true,
        "UmbracoPath": "~/umbraco",
        "TimeOutInMinutes": 20,
        "UseHttps": false,
        "Id": "7fdd5007-7eb0-4011-b238-36b5ee50536d"
      },
      "Hosting": {
        "Debug": false
      },
      "KeepAlive": {
        "DisableKeepAliveTask": false,
        "KeepAlivePingUrl": "{umbracoApplicationUrl}/api/keepalive/ping"
      },
      "RequestHandler": {
        "ConvertUrlsToAscii": "try"
      },
      "RuntimeMinification": {
        "dataFolder": "umbraco/Data/TEMP/Smidge",
        "version": "637510451273675926"
      },
      "Security": {
        "KeepUserLoggedIn": false,
        "UsernameIsEmail": true,
        "HideDisabledUsersInBackoffice": false,
        "UserPassword": {
          "RequiredLength": 10,
          "RequireNonLetterOrDigit": false,
          "RequireDigit": false,
          "RequireLowercase": false,
          "RequireUppercase": false,
          "MaxFailedAccessAttemptsBeforeLockout": 5
        },
        "MemberPassword": {
          "RequiredLength": 10,
          "RequireNonLetterOrDigit": false,
          "RequireDigit": false,
          "RequireLowercase": false,
          "RequireUppercase": false,
          "MaxFailedAccessAttemptsBeforeLockout": 5
        }
      },
      "Tours": {
        "EnableTours": true
      },
      "ModelsBuilder": {
        "ModelsMode": "PureLive",
        "Enable": true
      }
    }
  }
}

However in the Umbraco 9 beta release, the appsettings.json file that gets delivered when you install the dotnet template looks like this:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning"
      }
    }
  },
  "ConnectionStrings": {
    "umbracoDbDSN": ""
  },
  "Umbraco": {
    "CMS": {
      "Hosting": {
        "Debug": false
      }
    }
  }
}

This may be by design, to reduce the bloat of the appsettings file by assuming default values for everything and not having them all listed verbosely. It might also be that some of the keys have changed, been removed, moved to other config files, or things like this.

The problem is that we don't know whether any of the keys have changed from the alpha version to beta, or what options are available to add into the appsettings config. We made a guess that, for example, to set the ModelsBuilder mode to AppData we could copy the structure from the alpha version of appsettings into the beta file, and that seemed to work:

"Umbraco": {
    "CMS": {
      "Hosting": {
        "Debug": false
      },
      "Global": {
        "Id": "4d744b1d-7243-4052-91ac-4556596a0161"
      },
      "ModelsBuilder": {
        "ModelsMode": "AppData",
        "Enable": true
      }
    }
  }

But someone coming into the beta fresh without having seen the alpha versions would not have this to refer to.

We looked around and couldn't find any documentation on the appsettings.json config file for the beta version. It would be good to see a list of all the available keys and json structures, what options can be set for them, and what effect they have on the umbraco instance.

Does such documentation exist somewhere?

Thanks, Chris

sofietoft commented 3 years ago

Thanks for the detailed report @chris-evansnz !

We have yet to add some thorough docs on this new way of configuring a Umbraco project. I can assure you that it's at the very top of our list 💪

I'll ping the Unicore team, to hear if they already have something like it lying around!

sofietoft commented 3 years ago

Hi again @chris-evansnz !

It turns out that we do not have a full list of all available keys and JSON structures at the moment. When you're working with the JSON files however, you should be able to see the available options!

Also, I can assure you that getting the config docs updated is at the very top of our list material that needs updating. Keep an eye on this list, where we will link to all updated material for Umbraco 9: https://our.umbraco.com/documentation/Umbraco9Articles

chris-evansnz commented 3 years ago

Thanks @sofietoft - appreciate the update.

Can you explain a bit more what you mean by this: When you're working with the JSON files however, you should be able to see the available options ? Is there some kind of schema or sourcemap available that can give Intellisense in Visual Studio?

sofietoft commented 3 years ago

Of course! I should have been more clear on that.

Yes, there is some JSON schema that provides IntelliSense in a tool like Visual Studio. It's as far as I've understood, something that is currently manually maintained.

This new way of configuring a project is very new to me, so let me see if I can get someone to explain it a little better 😄

warrenbuckley commented 3 years ago

Hi @chris-evansnz Visual Studio, VSCode or JetBrains Rider should all be attempting to pick up the JSON Schema for you automatically.

jonat123 commented 2 years ago

Hello, @chris-evansnz I hope you are doing well 🙂

As you might know, Umbraco 9 was released some months ago now, and we have created documentation for the different configs in Umbraco 9.

They can be found here: https://our.umbraco.com/documentation/Reference/V9-Config/

I will therefore close down this issue 🙂

Regards Jonathan

umbraco / UmbracoDocs