Settings.xml
[!warning] Verouderd vanaf release 28.0 Dit onderwerp beschrijft het XML-formaat van het instellingenbestand en de overgang naar het JSON-formaat. Ondersteuning voor het XML-formaat eindigt met Invantive UniversalSQL release 28.0, gepland rond het begin van 2028. Dit onderwerp en alles wat erin staat, kan daarna worden verwijderd; Settings beschrijft het formaat dat overblijft.
Tot en met release 26.0 werden virtuele databases gedefinieerd met het bestand settings.xml en andere bestanden die aan het patroon settings*.xml voldoen. Vanaf release 27.0 leest Invantive UniversalSQL databasedefinities in plaats daarvan uit settings*.json, zoals beschreven in Settings. Bestaande XML-bestanden worden automatisch gemigreerd.
De concepten zijn ongewijzigd: het zoekpad, het samenvoegen van meerdere bestanden en de betekenis van databasegroepen, databases en datacontainers zijn in beide formaten gelijk. Alleen de notatie verschilt.
Waarom het formaat is veranderd
Het XML-formaat dateert van 2009 en kent twee problemen die een formaatwijziging oplost.
- Gereedschap: het lezen of genereren van een instellingenbestand vereist XPath en/of XSLT. De meeste talen verwerken JSON zonder extra bibliotheken. Het genereren van een instellingenbestand per klant of per omgeving wordt eerder een kwestie van tekstsjablonen dan van XML.
- Verouderde elementen: het XML-formaat bevat veel geschiedenis over de concepten van databaseconnectiviteit. Veel elementen worden niet meer ondersteund of zijn niet langer relevant. Het JSON-formaat gebruikt de huidige concepten, dus wat u leest is wat de term betekent.
Welk formaat wordt gebruikt
| Release | Behaviour |
|---|---|
| 26.0 en eerder | settings*. wordt gebruikt; een settings*.-bestand wordt genegeerd. |
| 26.1 (BETA van 27.0) | settings*. wordt gebruikt; een identiek benoemd settings*. wordt genegeerd en gebruikt om de JSON-variant te maken. |
| 27.0 | settings*. wordt gebruikt; een identiek benoemd settings*. wordt genegeerd en gebruikt om de JSON-variant te maken. |
| 28.0 | settings*. wordt gebruikt; het XML-formaat wordt niet langer ondersteund of gebruikt om de JSON-variant te maken. |
Release 26.1 is de BETA van release 27.0 en gedraagt zich er identiek aan: in de Invantive-releasenummering duidt een even tweede getal een productierelease aan en een oneven tweede getal de BETA van de volgende productierelease. Release 27.0 is daarom de eerste productierelease die settings*.json leest.
Voorrang geldt per bestandsnaam. Een settings-acme.json vervangt settings-acme.xml, terwijl een settings-other.xml zonder JSON-tegenhanger nog steeds wordt gelezen en gemigreerd.
Migratie
Er is moeite gedaan om de migratie zo eenvoudig mogelijk te maken.
De eerste keer dat een product van release 27.0 een settings*.xml-bestand leest waarvoor geen identiek benoemd .json-bestand bestaat, maakt het ernaast een functioneel identiek JSON-bestand aan. Het XML-bestand blijft ongewijzigd. Verouderde eigenschappen worden genegeerd.
Bestanden die door automatische detectie zijn geproduceerd (settings-discovery*.xml) worden nooit gemigreerd, omdat ze aan een specifieke hoofdrelease zijn gekoppeld.
Alleen het discovery-bestand van de draaiende release, settings-discovery-<version>.json in de databasesmap, wordt gelezen. Elk discovery-bestand in het XML-formaat, settings-discovery*.xml van welke versie ook, en elke settings-discovery-<version>.json van een andere versie wordt overgeslagen: elke release schrijft zijn eigen bestand, en een oudere zou dezelfde databases nogmaals onder oudere namen vermelden. Alle overige settings*.xml- en settings*.json-bestanden worden gelezen.
Bewerk na migratie het JSON-bestand. Wijzigingen in het XML-bestand werken vanaf release 26.1 niet meer.
Een gemigreerd bestand bevat een migration-lid dat vastlegt van welk bestand het is afgeleid, door wie, op welke machine, wanneer en met welke productversie. Het lid ontbreekt in een instellingenbestand dat met de hand is geschreven, dus de aanwezigheid ervan geeft aan dat een bestand is gemigreerd:
{ "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"
}
}
XML-bestanden verwijderen
Wanneer een omgeving alleen release 27.0 of nieuwer gebruikt, kunnen alle settings*.xml-bestanden veilig worden verwijderd zodra het JSON-formaatbestand bestaat. Bewaar een XML-bestand alleen zolang een product van release 26.0 of eerder dezelfde map leest, met de kanttekening dat zo'n product elke wijziging in het JSON-bestand negeert.
Verschillen in notatie
Beide formaten beschrijven exact dezelfde databases. De verschillen zijn:
<connection>wordtdatabasegenoemd (enkelvoud) ofdatabases(meervoud).<database>wordtdataContainergenoemd (enkelvoud) ofdataContainers(meervoud).- De elementen
<database>en<credentials>delen ééndataContainers-array, waarin het lidkindaangeeft welke van de twee een datacontainer is, met de waardedataContainerofcredentials. - Herhaalde elementen worden arrays met een meervoudige naam:
<group>wordtgroups,<provider>wordtproviders,<attribute>wordtattributesen<failover>wordtfailovers. - Ledennamen zijn consequent camelCase, dus
PasswordLabelin XML ispasswordLabelin JSON.
Structuur
De instellingenbestanden hebben de volgende structuur in XML-formaat; de volledige specificatie is beschikbaar in invantive-databases.xsd in de bijlagen.
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
Een database bestaat uit een of meer datacontainers. Datacontainers kunnen worden gedefinieerd met behulp van:
database: één voor elke lokaal gedefinieerde datacontainer;credentials: één, meerdere of alle datacontainers in een door Invantive Cloud beheerde database (via Invantive Credentials Server).
Met EditabilityType als een van:
Auto,ReadOnly,Hidden,
Met AuthenticationModeType één van:
Default,Database,Application.
De volgende elementen zijn uit de structuur weggelaten omdat ze verouderd zijn, maar XML-bestanden die deze bevatten worden nog steeds geaccepteerd:
- type fail-over-knoop,
- Invantive Web Service-datacontainers,
- attributes on
connection:encryptedDataCacheConnectionString,encryptedDataDictionaryConnectionString,PasswordLabel,PasswordHint,UserLogonCodeLabel,UserLogonCodeHint,passwordMode,userLogonCodeMode,defaultUserLogonCode,defaultPassword,enableRequestLogging, - kenmerk op
database:encryptedConnectionString, - kenmerk op
settings:sqlTrace,enableRequestLogging,forcedefault.
Voorbeelden
De volgende databasedefinitie biedt een PostgreSQL-database, de cloud-API's van het Nederlandse parlement en de Exact Online- en Salesforce-datacontainers van een door Invantive Cloud beheerde database. Dezelfde definitie in JSON-formaat wordt getoond 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>