AppSettings

Parametri applicativi, configurazioni ambiente e override runtime.

Questa pagina documenta le chiavi usate dal framework in appsettings.json e appsettings.{Environment}.json.

Convenzioni generali

• I valori sotto AppSettings sono letti come stringa e poi convertiti (bool/int) dal backend.
• Per flag booleani usare true|false.
• Per chiavi numeriche usare interi positivi (secondi/minuti/timeout).
• Le chiavi sono case-sensitive lato JSON.

Logging

Sezione top-level Logging:LogLevel (standard .NET). Valori ammessi per ogni chiave: Trace | Debug | Information | Warning | Error | Critical | None. Hot-reload.

• Logging:LogLevel:Default

Significato: livello di log di default per tutte le categorie non sovrascritte.

Default tipico: Warning.

• Logging:LogLevel:System

Significato: livello per la categoria System (runtime .NET).

• Logging:LogLevel:Microsoft

Significato: livello per la categoria Microsoft (ASP.NET Core, EF, hosting).

AppSettings - Core bootstrap

• firstRun

Significato: abilita il flusso di prima configurazione/provisioning.

Valori: true | false.

Default tipico: false.

• preScaffold

Significato: abilita pre-scaffolding di oggetti metadata/app.

Valori: true | false.

Default tipico: false.

• projectDataFolder

Significato: root progetto applicativo (es. CrmApp) usata per file, assembly e risorse runtime.

Valori: path assoluto filesystem.

• projectAssemblyName

Significato: assembly applicativo caricato dinamicamente.

Valori: path assoluto .dll.

• defaultSiteRoute

Significato: route iniziale client dopo bootstrap/login.

Valori: hash-route (es. #/).

• license-email

Significato: email/licenza installazione.

Valori: email valida.

AppSettings - Database e provider

• dbms

Significato: provider DB principale route dati.

Valori enum-like: mssql | mysql | postgresql | oracle | xml.

Default tipico: mssql.

• meta-dbms

Significato: provider DB metadata (route di sistema).

Valori enum-like: mssql | mysql | postgresql | oracle | xml.

Default tipico: uguale a dbms.

• allowMultipleDBMS

Significato: abilita convivenza provider multipli nel runtime.

Valori: true | false.

Default tipico: false.

• connection

Significato: connection string base usata da servizi/scaffolding.

Valori: connection string provider-specific.

• DataDBName

Significato: nome database dati di default.

Valori: nome DB.

• connectionByUser

Significato: usa connessione/contesto legato all'utente corrente in punti runtime specifici.

Valori: true | false.

Default tipico: false.

AppSettings - CRUD, query, filtri

• autoGeneratedQueryTimeout

Significato: timeout (secondi) query SQL autogenerate.

Valori: intero positivo.

Default tipico: 120.

• storedProcTimeout

Significato: timeout (secondi) esecuzione stored procedure.

Valori: intero positivo.

• enableServerSideCrudChangeLog

Significato: abilita logging lato server delle operazioni CRUD.

Valori: true | false.

Default tipico: true.

• optimisticCheckEnabled

Significato: abilita il controllo di concorrenza ottimistica sugli update: il salvataggio viene rifiutato se il record è stato modificato da un altro utente dopo la lettura (confronto del campo di versione/data_modifica). Evita sovrascritture silenziose in scenari multi-utente.

Valori: true | false. Hot-reload.

• logicDeleteField

Significato: campo globale per cancellazione logica (se non definito in metadata tabella).

Valori: nome colonna.

• logicDeleteValue

Significato: valore che rappresenta "record cancellato logicamente".

Valori: string/numero compatibile col tipo del campo.

Default tipico: 1.

• cacheDataMinutes

Significato: durata cache dati in minuti (quando caching route attivo).

Valori: intero positivo.

• cacheDataIncludedRoutes

Significato: whitelist route cacheabili.

Valori: lista route separata da virgole.

• cacheDataExcludedRoutes

Significato: blacklist route da escludere dalla cache.

Valori: lista route separata da virgole.

• traceQuery

Significato: abilita tracing query SQL con tempi esecuzione.

Valori: true | false.

Default tipico: false.

• sqlVerbose

Significato: abilita output SQL verboso in endpoint/tools che lo supportano.

Valori: true | false.

• logInvoke

Significato: abilita log invocazioni funzioni dinamiche/callback.

Valori: true | false.

AppSettings - Sicurezza, login, sessione

• customAuthentication

Significato: delega autenticazione a logica custom applicativa.

Valori: true | false.

• enableCookieAuthentication

Significato: controlla chi scrive il cookie di sessione k-user e con quale policy. Il backend espone in entrambe le modalita' lo stesso wire format (k-user=<urlencoded-json>), cambia solo il mittente e gli attributi del cookie.

Valori: true | false. Default: false.

Confronto sintetico delle due modalita':

### Comportamento single-session (modalita' true)

Ogni login genera un nuovo token che sovrascrive il precedente. Conseguenze pratiche:

- Se lo stesso utente si logga da due browser diversi (o due finestre anonime), l'ultimo login vince: il primo browser viene disconnesso con il messaggio "Sessione terminata: e' stato effettuato l'accesso con lo stesso utente da un altro browser." — sia navigando una pagina, sia facendo refresh.

- Il browser con l'ultimo login non subisce impatti.

- Due tab nello stesso browser non hanno questo problema: condividono lo stesso cookie, quindi il token si aggiorna su entrambe.

### Trappole note

- Se modifichi appsettings.json a mano mentre il backend e' running, serve un restart (l'editor AppSettings web fa il flush automaticamente).

- Dopo un flip da false a true, i cookie preesistenti non hanno il token → gli utenti devono rifare il login.

- I test E2E (backend-api-client.mjs) rilevano la modalita' automaticamente e funzionano in entrambi i casi.

• enableODATAAuthentication

Significato: abilita auth per endpoint OData.

Valori: true | false.

• enableHttpsRedirection

Significato: forza il redirect HTTP→HTTPS + HSTS. Default false (nessun redirect, niente HSTS): l'app risponde sia su HTTP sia su HTTPS. Impostare true SOLO su host con certificato HTTPS valido (in Startup.cs attiva UseHttpsRedirection/UseHsts).

Valori: true | false. Default: false. Riavvio.

Significato: abilita accesso ospite.

Valori: true | false.

• applyGrantByDefaultToGuest

Significato: applica grant di default anche all'utente guest.

Valori: true | false.

• grantDashSaveToGuest

Significato: consente salvataggio dashboard al guest.

Valori: true | false.

• default-role-id

Significato: ruolo assegnato in fallback/default.

Valori: intero (ID ruolo).

• sessionTimeoutMinutes

Significato: timeout sessione utente in minuti.

Valori: intero positivo.

Default tipico: 60.

• notifySessionExpirationBefore

Significato: anticipo (minuti) notifica scadenza sessione.

Valori: intero positivo.

Default tipico: 1 o 2 a seconda ambiente.

• enableUserLanguageSwitch

Significato: abilita switch lingua utente in UI.

Valori: true | false.

AppSettings - Password e policy credenziali

• IsPwdEncripted

Significato: indica se le password in store sono hashate.

Valori: true | false.

• encriptionMethod

Significato: algoritmo hash legacy usato per verifica password.

Valori enum-like: SHA1 | MD5.

Default tipico: SHA1.

• password_min_length e password_min_length

Significato: lunghezza minima password (nota: in alcuni file esiste variante con spazio finale nel nome chiave).

Valori: intero positivo.

Default tipico: 8.

AppSettings - Captcha, doppio token, URL applicative

• captcha_public_key

Significato: chiave pubblica captcha.

Valori: string.

• captcha_private_key

Significato: chiave privata captcha.

Valori: string.

• enableDoubleTokenAuthentication

Significato: abilita step di verifica token aggiuntivo nel flusso login/attivazione previsto.

Valori: true | false.

• site-url

Significato: URL base sito per link assoluti email/workflow.

Valori: URL assoluto.

• content-url

Significato: URL base contenuti/link di conferma (mailing, read-confirm, ecc.).

Valori: URL assoluto.

AppSettings - Email e notifiche mail

• email-host

Significato: host SMTP.

Valori: hostname/IP.

• email-port

Significato: porta SMTP.

Valori: intero (25, 465, 587, ...).

• email-ssl

Significato: abilita TLS/SSL SMTP.

Valori: true | false.

• email-user

Significato: username SMTP.

Valori: string.

• email-pwd

Significato: password SMTP.

Valori: string/segreto.

• email-sender-address-mailing

Significato: mittente email di mailing/notifiche.

Valori: email valida.

• email-sender-name-mailing

Significato: display name mittente mailing.

Valori: string.

• email-sender-address-registration

Significato: mittente email registrazione/attivazione.

Valori: email valida.

• email-admin-registration

Significato: destinatario amministrativo eventi registrazione.

Valori: email valida.

• email_confirm_token_subject

Significato: subject template email conferma token.

Valori: string.

• email_confirm_token_body

Significato: body template email conferma token.

Valori: string (anche HTML).

AppSettings - Upload e media

• uploadFolder

Significato: cartella root upload file/immagini.

Valori: path assoluto o virtual path risolto dal server.

• base64Image

Significato: forza gestione immagini in formato base64 dove previsto.

Valori: true | false.

AppSettings - Report e runtime report viewer

• ReportMode

Significato: modalità rendering report nel viewer.

Valori enum-like osservati: web (default fallback) e modalità custom gestite lato controller.

Nota: se assente, il backend usa fallback web.

• reportQueryTimeout

Significato: timeout query dataset report (secondi).

Valori: intero positivo.

AppSettings - Record translations (chiavi legacy in AppSettings)

• recordTranslationsEnabled

Significato: abilita traduzione record per campo.

Valori: true | false.

• recordTranslationsDefaultTableName

Significato: tabella default traduzioni record.

Valori: nome tabella.

• recordTranslationsTranslationJsonFieldName

Significato: nome campo JSON traduzioni.

Valori: nome colonna.

• recordTranslationsDefaultLanguage

Significato: lingua fallback traduzioni record.

Valori: culture code (es. it-IT, en-US).

• recordTranslationsFieldNames

Significato: elenco campi traducibili.

Valori: lista separata da virgole.

Sezioni top-level correlate (fuori da AppSettings)

• RecordTranslations:Enabled

Significato: switch principale runtime traduzioni record.

Valori: true | false.

• RecordTranslations:DefaultTableName

Significato: tabella fisica traduzioni.

Valori: nome tabella.

• RecordTranslations:TranslationJsonFieldName

Significato: campo JSON traduzioni.

Valori: nome colonna.

• RecordTranslations:DefaultLanguage

Significato: lingua fallback.

Valori: culture code.

• RecordTranslations:FieldNames

Significato: campi traducibili.

Valori: array di stringhe.

• Scheduler:Enabled

Significato: abilita hosted service scheduling.

Valori: true | false.

• Scheduler:PollSeconds

Significato: polling scheduler in secondi.

Valori: intero positivo.

• Scheduler:MaxTasksPerCycle

Significato: massimo task processati per ciclo.

Valori: intero positivo.

• Scheduler:RetryDelaySeconds

Significato: ritardo retry task falliti.

Valori: intero positivo.

• Scheduler:SqlCommandTimeoutSeconds

Significato: timeout SQL scheduler.

Valori: intero positivo.

• Notifications:Enabled

Significato: abilita subsystem notifiche realtime.

Valori: true | false.

• Notifications:Mode

Significato: modalità watcher backend notifiche.

Valori enum-like: SqlDependency | Polling.

• Notifications:PollSeconds

Significato: polling notifiche se Mode = Polling.

Valori: intero positivo.

• Authentication:OAuth:Enabled

Significato: abilita login OAuth/OIDC.

Valori: true | false.

• Authentication:OAuth:Provider

Significato: provider OAuth visualizzato/gestito.

Valori enum-like usato in config: Google (estendibile a provider custom compatibili OIDC).

• Authentication:OAuth:Authority

Significato: authority/issuer OIDC.

Valori: URL.

• Authentication:OAuth:ClientId

Significato: client id applicazione OAuth.

Valori: string.

• Authentication:OAuth:ClientSecret

Significato: client secret OAuth.

Valori: string/segreto.

• Authentication:OAuth:RequireHttpsMetadata

Significato: richiede metadati OIDC via HTTPS.

Valori: true | false.

• Authentication:OAuth:CallbackPath

Significato: path callback signin.

Valori: path assoluto.

• Authentication:OAuth:SignedOutCallbackPath

Significato: path callback signout.

Valori: path assoluto.

• Authentication:OAuth:AllowedReturnOrigins

Significato: whitelist origin di ritorno consentite.

Valori: array URL/origin.

• Authentication:OAuth:Scopes

Significato: scope richiesti al provider.

Valori: array stringhe (openid, profile, email, ...).

ADFS via OpenID Connect

ADFS 4.0+ (Windows Server 2016+) parla OIDC nativamente: l'integrazione con WUIC non richiede codice nuovo, basta la sezione Authentication.OAuth configurata sul tenant ADFS. La pipeline e' la stessa di Google/Auth0/Keycloak — Provider="OpenIdConnect" instrada il flusso su services.AddOpenIdConnect(...) in Startup.cs:264.

Pre-requisiti lato ADFS:

1. Federation Service Name raggiungibile in HTTPS dal backend WUIC (es. https://adfs.contoso.com/adfs).

2. Endpoint OIDC abilitato: verifica che https://adfs.contoso.com/adfs/.well-known/openid-configuration risponda 200 con il discovery document.

3. Application Group registrata in ADFS Management Console (adfs.msc → Application Groups → Add Application Group → "Server application accessing a web API"):

- Redirect URI: https://<host-wuic>/signin-oidc

- Annotare ClientId (auto-generato) e generare un ClientSecret.

4. Issuance Transform Rules sul Web API: emettere almeno email, name, upn come claim (servono al frontend per popolare il profilo utente).

Configurazione lato KonvergenceCore:

Trappole note:

• `RequireHttpsMetadata=true` obbligatorio in produzione: ADFS espone i metadati firmati su HTTPS; mai disabilitarlo se non in dev contro un ADFS con cert self-signed.
• `CallbackPath` deve corrispondere letteralmente al Redirect URI registrato in ADFS (case-sensitive sulla path). Se cambi uno, cambia anche l'altro.
• Scopes: ADFS supporta openid, profile, email, e custom scope definiti nelle Application Permissions. Se richiedi uno scope non concesso al client, ADFS risponde con invalid_scope durante il consent.
• Single Logout (SLO): SignedOutCallbackPath viene chiamato solo se ADFS e' configurato per emettere il logout token. Se manca, dopo il logout WUIC il browser resta loggato in ADFS e un nuovo login WUIC e' silent SSO.
• Coesistenza con LDAP: la sezione Authentication.OAuth (federazione browser-redirect) e Authentication.Ldap (bind diretto da username/password) sono indipendenti. Possono coesistere — il front-end mostra un pulsante "Login con ADFS" oltre al form locale.
• Provider distinto da Google: il branch Provider==Google in Startup.cs:241 usa AddGoogle() con scope cablati. Per ADFS impostare `Provider=OpenIdConnect` (non Google) altrimenti la pipeline punta a accounts.google.com.
• ADFS 2.0 / 3.0 (Windows Server 2008R2-2012R2): parlano solo WS-Federation o SAML 2.0, non OIDC. Per quei tenant servirebbe un PackageReference aggiuntivo (Microsoft.AspNetCore.Authentication.WsFederation o Sustainsys.Saml2) e un nuovo branch in Startup.ConfigureServices — fuori scope di questa sezione.

Authentication:Ldap (LDAP / Active Directory)

WUIC supporta autenticazione LDAP/AD come provider opzionale prima del login DB tradizionale (LDAP-first). Quando Authentication:Ldap:Enabled=true, il backend tenta una bind verso il directory server configurato; se la bind riesce e l'utente non esiste ancora nella tabella utenti locale, viene auto-provisionato con Authentication:Ldap:DefaultRoleId (o, in fallback, AppSettings:default-role-id). Se LDAP è offline e FallbackToDbOnFailure=true, il login ricade automaticamente sul provider DB — utile per garantire l'accesso admin/admin anche in caso di outage del directory server.

Esempio minimo:

Chiavi disponibili:

• Authentication:Ldap:Enabled

Significato: abilita il provider LDAP davanti al DB. Quando false, il flusso e' identico a un deploy senza la sezione.

Valori: true | false.

• Authentication:Ldap:Host

Significato: hostname del directory server (AD DC, OpenLDAP, ApacheDS).

Valori: string.

• Authentication:Ldap:Port

Significato: porta del directory server.

Valori: intero. Tipicamente 389 (plain o StartTLS) o 636 (LDAPS).

• Authentication:Ldap:UseSsl

Significato: apre la connessione direttamente in LDAPS (TLS at-connect).

Valori: true | false.

• Authentication:Ldap:UseStartTls

Significato: apre in plain e poi promuove a TLS via StartTLS extended op (RFC 4511).

Valori: true | false. Mutuamente esclusivo con UseSsl.

• Authentication:Ldap:BaseDn

Significato: DN base sotto cui cercare gli utenti.

Valori: string DN (es. DC=example,DC=com).

• Authentication:Ldap:UserSearchFilter

Significato: filter LDAP per individuare la entry utente. Il placeholder {username} viene sostituito con lo username (RFC 4515 escaping applicato lato C# per prevenire injection).

Valori: string filter. Default: (&(objectClass=user)(sAMAccountName={username})) (Active Directory). Per OpenLDAP usare tipicamente (&(objectClass=inetOrgPerson)(uid={username})).

• Authentication:Ldap:UsernameAttribute

Significato: attributo della entry da cui leggere lo username canonico (usato come username_column_name nella tabella utenti locale).

Valori: string. Default: sAMAccountName.

• Authentication:Ldap:DisplayNameAttribute

Significato: attributo da cui leggere il display name (usato come user_description_column_name).

Valori: string. Default: displayName.

• Authentication:Ldap:EmailAttribute

Significato: attributo da cui leggere l'email (usato come email_column_name).

Valori: string. Default: mail.

• Authentication:Ldap:BindDn

Significato: DN del service account read-only usato per la search. Vuoto = anonymous bind (alcuni AD lo permettono per ricerche limitate, OpenLDAP di solito no).

Valori: string DN.

• Authentication:Ldap:BindPassword

Significato: password del service account. Mai committare: usare secret manager/env var (Authentication__Ldap__BindPassword) o riempire post-install dall'editor AppSettings.

Valori: string/segreto.

• Authentication:Ldap:ConnectTimeoutSeconds

Significato: timeout di connessione (in secondi) verso il directory server. Allo scadere il login fa fallback al DB se FallbackToDbOnFailure=true.

Valori: intero positivo. Default: 5.

• Authentication:Ldap:FallbackToDbOnFailure

Significato: se LDAP e' irraggiungibile o ritorna errore non legato alle credenziali, ricade sul login DB tradizionale. Garantisce l'accesso admin/admin durante outage del directory.

Valori: true | false. Default: true.

• Authentication:Ldap:AutoProvision

Significato: al primo login LDAP riuscito di un utente sconosciuto al DB locale, crea automaticamente la riga in _metadati__tabelle.user_table_name (default utenti) con il default role.

Valori: true | false. Default: true.

• Authentication:Ldap:DefaultRoleId

Significato: id ruolo assegnato in auto-provisioning. Override di AppSettings:default-role-id. Se entrambi null, il default e' 1.

Valori: intero o null.

Trappole note

• Bind password mai committata: il template appsettings.linux.*.json usa __SET_LDAP_BIND_PASSWORD__ come placeholder; il deploy script la sostituisce. Per i template "dev" (appsettings.json, appsettings.Development.json) il valore di default e' la stringa vuota — mai un segreto reale.
• AD vs OpenLDAP filter: AD usa sAMAccountName, OpenLDAP usa uid. Cambiare di conseguenza UserSearchFilter e UsernameAttribute.
• StartTLS su porta 636: errore comune. La 636 e' LDAPS (UseSsl=true); StartTLS gira sulla 389.
• Nessun cambiamento al cookie path: utenti LDAP e DB ricevono lo stesso cookie k-user. La differenza e' solo come vengono autenticate le credenziali.
• Sentinel password: il provisioner inserisce '__LDAP__' come valore della password column locale per gli utenti auto-provisionati. Non viene mai usata per autenticare (la bind LDAP ha gia' validato), ma la colonna deve essere NOT NULL-compatibile.
• Toggle a runtime: tutte le chiavi Authentication:Ldap:* sono RestartAndLogout: editarle dall'AppSettings editor richiede restart pulito.

AppSettings - License

Chiavi della licenza WUIC (firma RSA verificata al bootstrap). Hot-reload.

• license-email

Significato: email a cui è intestata la licenza (vedi anche Core bootstrap).

Valori: email valida.

• license-payload

Significato: payload della licenza in Base64 (tier, feature abilitate, scadenza, fingerprint macchina). Letto e verificato contro license-signature + license-public-key-pem.

Valori: stringa Base64.

• license-signature

Significato: firma RSA del license-payload. Se non valida, la licenza è rifiutata e le feature gated restano disattive.

Valori: stringa Base64.

• license-public-key-pem

Significato: chiave pubblica RSA (PEM) usata per verificare la firma. La chiave privata non lascia mai la macchina di emissione.

Valori: PEM.

SQL Retry (SqlMapperRetry)

Retry automatico con backoff sulle operazioni SQL transienti (deadlock, timeout, connessione persa). Tutte le chiavi richiedono riavvio.

• SqlMapperRetry:Enabled

Significato: abilita il retry automatico sugli errori SQL transienti.

Valori: true | false.

• SqlMapperRetry:MaxAttempts

Significato: numero massimo di tentativi prima di propagare l'errore.

Valori: intero positivo.

• SqlMapperRetry:BaseDelayMs

Significato: ritardo base (ms) per il backoff esponenziale tra i tentativi.

Valori: intero positivo.

• SqlMapperRetry:UseJitter

Significato: aggiunge jitter casuale al delay per evitare thundering-herd.

Valori: true | false.

• SqlMapperRetry:RetryReadOperationsOnly

Significato: limita il retry alle sole operazioni di lettura (le write non-idempotenti non vengono ritentate).

Valori: true | false.

• SqlMapperRetry:RetryOnTransaction

Significato: consente il retry anche quando l'operazione è dentro una transazione esplicita.

Valori: true | false.

Crash Reporting (CrashReporting)

Invio degli stacktrace anonimizzati al server crash-reporter WUIC. Richiede consenso GDPR esplicito prima dell'attivazione. Tutte le chiavi richiedono riavvio (middleware/hosted service registrati a startup in base a Enabled).

• CrashReporting:Enabled

Significato: invia i dettagli d'errore anonimizzati al server privato WUIC. Richiede il consenso GDPR esplicito prima dell'attivazione.

Valori: true | false.

• CrashReporting:UpstreamUrl

Significato: endpoint del receiver. Default https://errors.wuic-framework.com. Da sovrascrivere solo per deploy on-prem self-hosted.

Valori: URL.

• CrashReporting:ClientId

Significato: override del client id. Se vuoto, viene usata l'email dal payload di licenza come client_id autoritativo.

Valori: string.

• CrashReporting:DisclaimerAcceptedVersion

Significato: campo di audit read-only impostato dal flusso di consenso. Incrementato quando il testo del disclaimer cambia (forza il re-consenso).

Valori: string.

• CrashReporting:DisclaimerAcceptedAt

Significato: timestamp di audit read-only impostato dal flusso di consenso.

Valori: string (data/ora).

• CrashReporting:MaxQueueSize

Significato: capacità del channel bounded; le entry più vecchie vengono scartate sotto crash-storm sostenuti.

Valori: intero positivo.

• CrashReporting:MaxBreadcrumbsLen

Significato: limite dei breadcrumb per report (byte UTF-8). Troncato se superato.

Valori: intero positivo.

• CrashReporting:DedupTtlSeconds

Significato: finestra entro cui stack hash identici vengono contati come duplicati.

Valori: intero positivo.

• CrashReporting:DedupFlushEvery

Significato: flush ogni N-esima occorrenza ripetuta (1 = nessun dedup, invio sempre).

Valori: intero positivo.

RAG Chatbot (LLM)

Configurazione del componente <wuic-rag-chatbot> e dell'engine RAG .NET (WuicRagEngine). Le chiavi sono lette hot-reload dal backend .NET. Non hard-coded.

• rag-llm-provider

Significato: provider del modello conversazionale. Va impostato esplicitamente. anthropic usa il formato Anthropic (Claude); openai/openrouter/ollama usano un endpoint OpenAI-compatible. ollama punta a un Ollama locale via rag-llm-base-url (es. http://HOST:11434/v1). Se vuoto o non impostato il chatbot resta in retrieval-only (nessun LLM invocato): non c'è un provider di default.

Valori: anthropic | openai | openrouter | ollama | vuoto (= retrieval-only, nessun LLM).

• rag-llm-api-key

Significato: UNICA fonte della api key, indipendente dal provider scelto sopra. Valore speciale agent-sdk = usa l'Agent SDK (claude CLI) via subscription invece dell'API a consumo, se installato. Per ollama una key dummy (es. ollama) e' sufficiente. Vuoto = LLM disabilitato (solo retrieval). Mai committare in repo: usare secret manager / env var override.

Valori: string (api key del provider) | agent-sdk | ollama (dummy).

• rag-llm-base-url

Significato: override dell'endpoint del provider. Obbligatorio per `ollama` (es. http://HOST:11434/v1). Vuoto = default per provider (https://api.anthropic.com, https://api.openai.com/v1, https://openrouter.ai/api/v1).

Valori: URL.

• rag-llm-default-chat-model

Significato: modello usato dal chatbot per ogni nuovo turn (determina anche il context window max).

Valori: dipende dal provider, es. claude-haiku-4-5-20251001 (anthropic) | qwen2.5-coder:32b (ollama).

• rag-auto-compact-threshold

Significato: soglia in numero di turn oltre la quale il backend lancia automaticamente un compact best-effort pre-Ask (riassume i turn vecchi in _rag_chat_sessions.context_summary). Settare a 0 per disabilitare l'auto-compact (l'utente puo comunque triggerare /compact manualmente via UI).

Valori: intero >=0. Default consigliato: 30.

Note operative

• In produzione usare sempre secret manager/variabili ambiente per password/token (email-pwd, ClientSecret, captcha key, ecc.).
• Se abiliti allowMultipleDBMS, validare che dbms e meta-dbms siano entrambi supportati dal deploy.
• Per notifiche realtime, Notifications:Mode=SqlDependency richiede setup SQL compatibile; in alternativa usare Polling.

appsettings.json reale (snapshot)