invantive documentation
Forum di supporto InvantiveAccedi / Registrati

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*.xml è utilizzato; un file settings*.json viene ignorato.
26.1 (BETA di 27.0) settings*.json è utilizzato; un settings*.xml con lo stesso nome viene ignorato e utilizzato per creare la variante JSON.
27.0 settings*.json è utilizzato; un settings*.xml con lo stesso nome viene ignorato e utilizzato per creare la variante JSON.
28.0 settings*.json è 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> è denominato database (singolare) o databases (plurale).
  • <database> è denominato dataContainer (singolare) o dataContainers (plurale).
  • Gli elementi <database> e <credentials> condividono un unico array dataContainers, nel quale il membro kind indica quale dei due sia un data container, usando il valore dataContainer o credentials.
  • Gli elementi ripetuti diventano array con un nome al plurale: <group> diventa groups, <provider> diventa providers, <attribute> diventa attributes e <failover> diventa failovers.
  • I nomi dei membri sono coerenti: camelCase, quindi PasswordLabel in XML corrisponde a passwordLabel in 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:

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>