Settings.xml
[!warning] Obsoleto a partire dalla release 28.0 Questo argomento descrive il formato XML del file di impostazioni e la transizione al formato JSON. Il supporto del formato XML termina con la release 28.0 di Invantive UniversalSQL, prevista intorno all'inizio di 2028. Questo argomento e tutto il suo contenuto possono quindi essere eliminati; Settings descrive il formato che rimane.
Fino alla release 26.0 inclusa, i database virtuali erano definiti tramite il file settings.xml e altri file corrispondenti al pattern settings*.xml. A partire dalla release 27.0, Invantive UniversalSQL legge invece le definizioni dei database da settings*.json, come descritto in Settings. I file XML esistenti vengono migrati automaticamente.
I concetti non cambiano: il percorso di ricerca, la fusione di più file e il significato di gruppi di database, database e contenitori di dati sono gli stessi in entrambi i formati. Cambia solo la notazione.
Perché il formato è cambiato
Il formato XML risale a 2009 e presenta due problemi che un cambio di formato risolve.
- Strumenti: leggere o generare un file di impostazioni richiede XPath e/o XSLT. La maggior parte dei linguaggi analizza JSON senza librerie aggiuntive. Generare un file di impostazioni per cliente o per ambiente diventa un esercizio di template di testo anziché XML.
- Elementi obsoleti: il formato XML contiene molta storia sui concetti di connettività ai database. Molti elementi non sono più supportati o rilevanti. Il formato JSON utilizza i concetti attuali, quindi ciò che si legge corrisponde al significato del termine.
Quale formato viene utilizzato
| Release | Behaviour |
|---|---|
| 26.0 e precedenti | settings*. è utilizzato; un file settings*. viene ignorato. |
| 26.1 (BETA di 27.0) | settings*. è utilizzato; un settings*. con lo stesso nome viene ignorato e utilizzato per creare la variante JSON. |
| 27.0 | settings*. è utilizzato; un settings*. con lo stesso nome viene ignorato e utilizzato per creare la variante JSON. |
| 28.0 | settings*. è utilizzato; il formato XML non è più supportato né utilizzato per creare la variante JSON. |
La release 26.1 è la BETA della release 27.0 e si comporta in modo identico ad essa: nella numerazione delle release Invantive un secondo numero pari indica una release di produzione e un secondo numero dispari indica la BETA della successiva release di produzione. La release 27.0 è quindi la prima release di produzione a leggere settings*.json.
La precedenza si applica per nome di file. Un settings-acme.json sostituisce settings-acme.xml, mentre un settings-other.xml senza un equivalente JSON viene comunque letto e migrato.
Migrazione
Si è cercato di rendere la migrazione il più semplice possibile.
La prima volta che un prodotto della release 27.0 legge un file settings*.xml per il quale non esiste un file .json con lo stesso nome, crea accanto ad esso quel file JSON funzionalmente identico. Il file XML resta invariato. Le proprietà obsolete vengono ignorate.
I file prodotti dal discovery automatico (settings-discovery*.xml) non vengono mai migrati, poiché sono associati a una specifica release principale.
Viene letto solo il file di discovery della release in esecuzione, settings-discovery-<version>.json, nella cartella dei database. Ogni file di discovery in formato XML, settings-discovery*.xml di qualsiasi versione, e ogni settings-discovery-<version>.json di un'altra versione viene ignorato: ogni release scrive il proprio, e uno più vecchio elencherebbe gli stessi database una seconda volta con nomi precedenti. Vengono letti tutti gli altri file settings*.xml e settings*.json.
Dopo la migrazione, modificare il file JSON. Le modifiche apportate al file XML non hanno più effetto a partire dalla release 26.1.
Un file migrato contiene un membro migration che registra da quale file è stato derivato, da chi, su quale macchina, quando e con quale versione del prodotto. Il membro è assente in un file di impostazioni scritto a mano, quindi la sua presenza è ciò che identifica un file come migrato:
{ "migration":
{ "sourceFileNamePath": "C:\\Users\\john.doe\\invantive\\settings.xml"
, "migratedBy": "ACME\\john.doe"
, "migratedOn": "WS0001"
, "migrationDate": "2026-08-05T08:15:00.4608219Z"
, "migratedUsing": "27.0.1.1234"
}
}
Rimozione dei file XML
Quando un ambiente utilizza solo la release 27.0 o successive, tutti i file settings*.xml possono essere rimossi in sicurezza una volta che esiste il file in formato JSON. Conservare un file XML solo finché un prodotto della release 26.0 o precedente legge la stessa cartella, tenendo presente che tale prodotto ignora ogni modifica apportata al file JSON.
Differenze nella notazione
Entrambi i formati descrivono esattamente gli stessi database. Le differenze sono:
<connection>è denominatodatabase(singolare) odatabases(plurale).<database>è denominatodataContainer(singolare) odataContainers(plurale).- Gli elementi
<database>e<credentials>condividono un unico arraydataContainers, nel quale il membrokindindica quale dei due sia un data container, usando il valoredataContainerocredentials. - Gli elementi ripetuti diventano array con un nome al plurale:
<group>diventagroups,<provider>diventaproviders,<attribute>diventaattributese<failover>diventafailovers. - I nomi dei membri sono coerenti: camelCase, quindi
PasswordLabelin XML corrisponde apasswordLabelin JSON.
Struttura
I file di impostazioni hanno la seguente struttura in formato XML; la specifica completa è disponibile in invantive-databases.xsd negli allegati.
classDiagram
direction TB
class settings:::classDiagram {
+VersionUpdatedBy: string
+VersionUpdatedOn: string
+VersionUpdateDate: dateTime
+version: string
+default: string
}
class group:::classDiagram {
+name: string
+comment: string
+shortDescription: string
+description: string
+id: string
+sortingOrder: int
+createdBy: string
+createdOn: string
+creationDate: dateTime
+iconResourceName16: string
+iconResourceName32: string
}
class connection:::classDiagram {
+name: string
+id: string
+description: string
+shortDescription: string
+comment: string
+sqlTrace: boolean = false
+starred: boolean = false
+sortingOrder: int
+authentication: AuthenticationModeType
+IconResourceName16: string
+manual: boolean = false
+createdBy: string
+createdOn: string
+creationDate: dateTime
+lastUsedDate: dateTime
+forceNative: boolean = false
+dataCacheConnectionString: string
+iuidSource: string
+dataDictionaryConnectionString: string
}
class provider:::classDiagram {
+createdBy: string
+createdOn: string
+creationDate: dateTime
+comment: string
+order: int
+file: string
+class: string
}
class attribute:::classDiagram {
+code: string
+value: string
}
class credentials:::classDiagram {
+database: string
+server: string
+datacontainers: string
+order: int
+createdBy: string
+createdOn: string
+creationDate: dateTime
+description: string
+comment: string
+defaultUserLogonCode: string
+userLogonCodeMode: EditabilityType
+defaultPassword: string
+PasswordLabel: string
+PasswordHint: string
+UserLogonCodeLabel: string
+UserLogonCodeHint: string
+passwordMode: EditabilityType
}
class database:::classDiagram {
+connectionString: string
+AllowConnectionStringRewrite: boolean = true
+AllowConnectionPooling: boolean = true
+order: int
+createdBy: string
+createdOn: string
+creationDate: dateTime
+description: string
+comment: string
+alias: string
+provider: string
+defaultUserLogonCode: string
+userLogonCodeMode: EditabilityType
+defaultPassword: string
+PasswordLabel: string
+PasswordHint: string
+UserLogonCodeLabel: string
+UserLogonCodeHint: string
+passwordMode: EditabilityType
}
settings "1" *-- "0..*" group : group
group "1" *-- "0..*" connection : connection
connection "1" *-- "0..*" provider : provider
provider "1" *-- "0..*" attribute : attribute
connection "1" *-- "0..*" database : database
connection "1" *-- "0..*" credentials : credentials
Un database è costituito da uno o più data container. I contenitori di dati possono essere definiti utilizzando:
database: uno per ogni contenitore di dati definito localmente;credentials: uno, più o tutti i data container in un database gestito da Invantive Cloud (tramite Invantive Credentials Server).
Con EditabilityType uno dei seguenti:
Auto,ReadOnly,Hidden,
Con AuthenticationModeType uno di:
Default,Database,Application.
Gli elementi seguenti sono stati esclusi dalla struttura perché obsoleti, ma i file XML che li contengono saranno comunque accettati:
- tipo di nodo di failover,
- Contenitori di dati del Web Service di Invantive,
- attributes on
connection:encryptedDataCacheConnectionString,encryptedDataDictionaryConnectionString,PasswordLabel,PasswordHint,UserLogonCodeLabel,UserLogonCodeHint,passwordMode,userLogonCodeMode,defaultUserLogonCode,defaultPassword,enableRequestLogging, - attributo su
database:encryptedConnectionString, - attributo su
settings:sqlTrace,enableRequestLogging,forcedefault.
Esempi
La seguente definizione di database fornisce un database PostgreSQL, le API cloud del parlamento olandese e i contenitori di dati Exact Online e Salesforce di un database gestito Invantive Cloud. La stessa definizione in formato JSON è mostrata in Settings.
<?xml version="1.0" encoding="utf-8"?>
<settings
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="5"
>
<group
name="ACME"
sortingOrder="0"
shortDescription="ACME"
>
<connection
name="ACME"
sortingOrder="10"
authentication="Database"
>
<database
order="10"
alias="db"
provider="PostgreSql"
userLogonCodeMode="Hidden"
passwordMode="Hidden"
connectionString="Server=host.acme.eu;Database=xxacme;User Id=xxacme_user;Password=secret;CommandTimeout=3600"
AllowConnectionStringRewrite="false"
/>
<database
order="20"
alias="twk"
provider="TweedeKamerNl"
AllowConnectionPooling="false" />
<credentials
order="30"
description="Exact Online and Salesforce database"
database="acme-exact-online-salesforce"
datacontainers="*"
userLogonCodeMode="Hidden"
passwordMode="Hidden"
defaultUserLogonCode="john.doe@acme.eu"
defaultPassword="secret"
/>
</connection>
</group>
</settings>