Chaîne de connexion

NTiConnection se configure par une chaîne de connexion ADO.NET classique, au format clé=valeur;clé=valeur. Cette page est la référence exhaustive des mots-clés NTi 5 et des propriétés NTiConnection correspondantes.

Règles générales

Les mots-clés sont insensibles à la casse, et plusieurs synonymes sont acceptés pour la compatibilité v4.
Un mot-clé inconnu est ignoré (compatibilité v4, une chaîne de connexion v4 se réutilise telle quelle).
Une valeur invalide d'un mot-clé connu lève immédiatement, dès l'affectation de la chaîne. Il n'y a jamais de repli silencieux sur une valeur par défaut.
Une fois la connexion ouverte, la configuration est figée, et le mot de passe est expurgé de ConnectionString (sauf persist security info=true). Voir l'article sur la connexion pour le détail.

using Aumerial.Data.Nti;

await using var connection = new NTiConnection(
    "server=MYIBMI;user=MYUSER;password=MYPASSWORD;" +
    "ssl=true;pooling=true;max pool size=20;" +
    "default schema=MYLIB;naming=sql;application name=OrderApi");
await connection.OpenAsync();

Serveur et identité

Propriété	Mots-clés	Défaut	Description
`Server`	`server` `host` `system` `dsn` `datasource` `data source`	(obligatoire)	Nom DNS ou adresse IP de l'IBM i.
`Username`	`user` `user id` `userid` `uid`	(obligatoire)	Profil utilisateur IBM i.
`Password`	`password` `pwd`	(obligatoire)	Mot de passe (tous niveaux `QPWDLVL` supportés).
`AdditionalFactor`	`additional factor` `additionalfactor` `mfa` `2fa`	aucun	Facteur d'authentification supplémentaire statique (TOTP...).
`AdditionalFactorProvider`	(propriété seule)	aucun	Rappel synchrone invoqué au signon d'une session physique, qui reçoit un contexte (hôte, utilisateur). Prime sur la variante async.
`AdditionalFactorAsyncProvider`	(propriété seule)	aucun	Variante asynchrone (coffres, prompts). Sur `OpenAsync`, elle est attendue nativement avec le jeton de l'appelant, donc annulable. Sur `Open` synchrone, elle démarre hors `SynchronizationContext` avec une attente non bornée, donc à vous de borner les prompts interactifs.
`LicenseLibrary`	`license library`	`KNTI`	Bibliothèque contenant la licence NTi sur la partition.
(aucune)	`isvid`	aucun	Clé éditeur (intégrations ISV).
(aucune)	`persist security info` `persistsecurityinfo`	`false`	Conserve le mot de passe dans `ConnectionString` après ouverture (défaut : retiré).
`ConnectionTimeout` (lecture seule)	`connect timeout` `connection timeout` `timeout`	0 (illimité)	Délai d'établissement de connexion, en secondes. 0 = infini.

Réseau et transport

Propriété	Mots-clés	Défaut	Description
`UseSSL`	`ssl` `tls` `use ssl` `use tls`	`false`	Chiffre les connexions aux serveurs hôtes en TLS. Les ports par défaut basculent alors sur leurs variantes 94xx.
`Untrusted`	`untrusted`	`false`	Accepte tout certificat serveur (environnements de test uniquement).
`UsePortMapper`	`use mapper` `use port mapper`	`false`	Résout les ports via le port mapper (449) au lieu des ports fixes.
`SignonPort`	`signon port`	8476 (9476 en TLS)	Port du serveur signon.
`DatabasePort`	`database port`	8471 (9471 en TLS)	Port du serveur database.
`CommandPort`	`command port`	8475 (9475 en TLS)	Port du serveur commande/programme.
`MapperPort`	`mapper port`	449	Port du port mapper.
`Compress`	`compress` `use compression`	`true`	Compression RLE des grandes réponses.

Pool de connexions

Propriété	Mots-clés	Défaut	Description
`Pooling`	`pool` `pooling` `pooled` `connection pool` `connection pooling`	`false`	Active le pool de connexions. Inactif par défaut pour compatibilité v4, il doit être activé explicitement, ce qui est fortement recommandé pour le web.
`PoolSize`	`pool size` `poolsize`	50	Taille cible du pool.
`LimitPoolSize`	`limit pool size` `limitpoolsize` `pool limit` `poollimit`	`false`	Fait de `PoolSize` un plafond dur.
`PoolSize` + `LimitPoolSize`	`maxpoolsize` `max pool size`	(non défini)	Raccourci : fixe la taille ET active le plafond.

Données et texte

Propriété	Mots-clés	Défaut	Description
`DefaultCcsid`	`default ccsid` `defaultccsid`	aucun	Assertion « le texte non tagué est dans cette page ». Sans elle, CHAR/VARCHAR CCSID 65535 = FOR BIT DATA (binaire, jamais converti). Indispensable pour lire du texte sur les systèmes QCCSID=65535. Ne surcharge jamais un CCSID de colonne réel.
`ForceTranslate`	`force translate`	aucun	Reprend la sémantique v4, en décodant les champs BINARY/VARBINARY/ROWID comme du texte dans ce CCSID. Ne touche jamais le FOR BIT DATA.
(aucune)	`text errors` `texterrors`	`lenient`	Mode d'erreur des conversions : `lenient` (décodage tolérant U+FFFD, encodage strict), `strict`, `legacy` (substitution « ? », plein v4).
`TrimCharFields`	`trim`	`true`	Retire les blancs de fin des CHAR/GRAPHIC fixes.
`LegacyNullSemantics`	`null semantics` `legacy nulls`	`false`	Reprend la sémantique v4 des NULL, avec `GetValue` et `ExecuteScalar` qui rendent `null` au lieu de `DBNull`.
(aucune)	`roundoption` `round option`	défaut serveur	Mode d'arrondi DECFLOAT (registre serveur).
`LOBMaxSize`	`lob threshold`	15360	Seuil (octets) au-delà duquel un LOB passe par locator au lieu d'être lu en ligne.

Exécution et lecture

Propriété	Mots-clés	Défaut	Description
`BlockingFactor`	`blocking` `blocking factor` `blockingfactor`	0 (adaptatif)	Lignes par bloc de fetch. Par défaut, la valeur est dimensionnée automatiquement sur la largeur de ligne pour viser `block size`, avec un plafond à 32767. Une valeur supérieure à 0 force un nombre fixe, comme en v4.
`FetchBlockSize`	`block size` `blocksize`	512	Taille cible du bloc de fetch, en Kio, pour le dimensionnement automatique.
`FetchAhead`	`fetch ahead` `fetchahead`	`false`	Recouvre réseau et décodage, en demandant le bloc suivant pendant la lecture du bloc courant.

Contexte SQL

Propriété	Mots-clés	Défaut	Description
`DefaultDatabase`	`default schema` `default database` `default collection` `schema` `database` `deault schema` (typo v4 conservée)	aucun	Schéma courant de la session (`SET CURRENT SCHEMA`). Modifiable à chaud via `ChangeDatabase`.
`NamingConvention`	`naming` `naming convention`	`sql`	Convention de nommage : `sql` (`LIB.OBJ`) ou `sys` (`LIB/OBJ`, liste de bibliothèques). Le volet EF Core exige `sql`.

Identité client (accounting)

Propriété	Mots-clés	Défaut	Description
`ApplicationName`	`application name` `applicationname`	`.NET Application`	Nom d'application poussé au serveur (audit/accounting).
`ClientAccounting`	`client accounting` `clientaccounting`	aucun	Code comptable client.
`ClientUserIdentifier`	`client user identifier`	aucun	Identifiant utilisateur final (traçabilité).
`ClientProgramIdentifier`	`client program identifier`	aucun	Identifiant du programme client.

Note sur la clé de pool

Le pool de connexions est indexé par la configuration complète, identité client comprise, avec application name, client accounting, client user identifier et client program identifier qui font partie de la clé de pool. Deux identités distinctes ne partagent donc jamais un pool. Le mot de passe, lui, n'entre jamais en clair dans la clé.

Et maintenant ?

Connexion : cycle de vie, pooling, TLS, MFA, annulation
Vue d'ensemble : architecture et fonctionnalités du provider
Guide de démarrage rapide : première connexion et premiers appels IBM i