Referenčni priročnik ukazne vrstice: wkl-office

wkl-office je orodje ukazne vrstice WKL Office SDK. Vsa druga orodja SDK, na primer opravila MSBuild in opravila za Visual Studio Code, kličejo isto kodo. Zato se ukaz vede enako, ne glede na to, od kod ga zaženete.

wkl-office <command> <project.acproj | folder | file> [options]
wkl-office diff <project.acproj> <object | file> [options]
wkl-office call <project.acproj | database> <function> [argument ...] [options]
wkl-office test <project.acproj> [options]
wkl-office texts export | import <project.acproj> [<file.csv>]
wkl-office addin install | remove | status
wkl-office settings list | get <key> | set <key> [<value>]

Če ob klicu wkl-office navedete možnost, ki je izbrani ukaz ne pozna (na primer --accde pri ukazu export), možnost, ki je ne pozna noben ukaz, ali napačno vrednost ali če manjka obvezen argument, program ne izvede ničesar in se konča z izhodno kodo 1. Na standardni izhod za napake izpiše eno vrstico z imenom ukaza in opisom napake ter napotek na wkl-office --help. Celotna navodila za uporabo dobite, če wkl-office zaženete brez argumentov. wkl-office --help (ali -h, -?, help) jih izpiše na standardni izhod in se konča z izhodno kodo 0.

Na projektu naenkrat le eno izvajanje. Ukazi, ki pišejo (build, rebuild, run, open, validate, accde, export, import, status, sync, commit, roundtrip, deliver, msi, test, texts), imajo med delom odprto datoteko obj/wkl-sdk.lock poleg projektne datoteke. Če medtem zaženete drug tak ukaz, iz terminala, iz dotnet build ali iz dodatka, se ta takoj konča z izhodno kodo 10 in ne spremeni ničesar. Sporočilo navede, kdo ima projekt zaklenjen: ID procesa, program, ukaz in od kdaj. Zaklepanje se sprosti s koncem izvajanja, tudi če je bilo prisilno prekinjeno, zato ni treba ničesar pospravljati: zaklenjen je projekt, dokler je datoteka odprta, ne dokler obstaja. Datoteka ostane s podatki zadnjega izvajanja in sama po sebi nič ne pomeni; mapo obj lahko izbrišete. Ukazi check, call, changes, diff, push, new, migrate in addin projekta ne zaklenejo.

En Access naenkrat na računalniku (izbirno). Kadar isti računalnik hkrati uporablja več oseb ali avtomatiziranih postopkov, se izvajanja programa Access lahko ovirajo: pogovorno okno enega izvajanja na primer ustavi drugo, ponovna registracija komponent pa vpliva na vse, ki tečejo hkrati. Udeleženci se zato lahko dogovorijo za skupno datoteko zaklepanja, ki jo navedete z --lock-file <datoteka> ali s spremenljivko okolja WKL_ACCESS_LOCK_FILE. Vsak ukaz, ki zažene Access (build, rebuild, run, open, validate, accde, export, import, status, sync, commit, roundtrip, migrate, deliver, msi, call, test), to datoteko ustvari, preden zažene Access, in jo ima odprto do konca izvajanja. Enako ravnajo opravila MSBuild (le prek spremenljivke okolja) in operacije dodatka. Če datoteko že uporablja drugo izvajanje ali drugo orodje, ukaz počaka največ toliko sekund, kot določa --lock-wait (privzeto 600, pri MSBuild prav tako 600), in na standardnem izhodu za napake enkrat izpiše, kdo jo uporablja. Če se datoteka v tem času ne sprosti, se konča z izhodno kodo 10 in ne spremeni ničesar. Operacija dodatka čaka enako kot na zaklenjen projekt in prikazuje zaklepanje računalnika <datoteka>: <imetnik>.

• Datoteka ima v vsaki vrstici en par ime: vrednost: holder: (vrednost WKL_ACCESS_LOCK_HOLDER, sicer uporabniško ime), since: (čas UTC), purpose: (ukaz in projekt) in process: (ID procesa in program).
• SDK datoteko ustvari tako, da jo Windows samodejno izbriše, ko se izvajanje konča, tudi ob prisilni prekinitvi ali sesutju. Zato nikoli ne ostane zaklepanje, ki bi ga bilo treba odstraniti ročno.
• Če je datoteko ustvarilo drugo orodje (na primer skript, ki jo pred izvajanjem ustvari, le če še ne obstaja, in jo po izvajanju izbriše), SDK počaka nanjo in je nikoli ne izbriše.
• Skript, ki ima zaklepanje že sam in nato pokliče wkl-office, nastavi WKL_ACCESS_LOCK_HELD na pot datoteke. SDK potem upošteva zaklepanje klicatelja in ne čaka nanj.
• Dokler ima SDK datoteko odprto, jo Test-Path najde. Prebrati pa jo more le program, ki med branjem dovoli njeno brisanje, v PowerShellu [IO.File]::Open($path, 'Open', 'Read', 'ReadWrite, Delete'); Get-Content sporoči, da je datoteka v uporabi.

Če datoteke zaklepanja ne navedete, nič od tega ne velja.

wkl-office new <folder> [-n <name>] [--json]

Ustvari prazen projekt v novi ali prazni mapi: <name>.acproj, source/ s prazno datoteko references.json, .gitignore za build/ in obj/ ter .vscode/tasks.json. Ime postane ime datoteke podatkovne zbirke in ime njenega projekta VBA, zato mora biti veljaven identifikator VBA: na začetku črka, nato črke, števke in _, največ 64 znakov. Če ime ni veljaven identifikator ali mapa ni prazna, se ukaz konča z izhodno kodo 1.

Nastavitve SDK pod newProjects določajo mape izvornih datotek, gradnje in izdaje novega projekta (SourceRoot, BaseOutputPath, DeliveryRoot), njegov nevtralni jezik, ali potrebuje 32- ali 64-bitni Access, in konfiguracije poleg konfiguracij Debug in Release. Če nastavitve navajajo mapo projektov (newProjects.root), se projekt, naveden samo z imenom (wkl-office new Stranke), ustvari v njej.

wkl-office check <project.acproj> [-c <name>] [--json]

Prebere projektno datoteko in vse izvorne datoteke ter nato preveri računalnik. Programa Access ne zažene.

• Izvorne datoteke: projektna datoteka, references.json, application/properties.json, vsaka shema tabele (tudi to, ali se ime datoteke ujema s tabelo), podatkovne datoteke tabel s pravilom SeedData ali FullData vrstico za vrstico, relacije, mape objektov (nepričakovane datoteke, standardni modul in modul razreda z istim imenom), nastavitve strani poročil, zaključna funkcija, AppMode in ograde kontrolnikov WKL; če ima projekt izdajo, tudi delivery-settings.json in vsak profil izdaje, vključno z načinom, ki ga določa njegova konfiguracija gradnje (delivery-settings.json).
• Poverilnice in podatki, vezani na računalnik: vsaka datoteka objekta, podatkov, traku in modela (tudi datoteke predloge), vrstico za vrstico. Geslo v povezovalnem nizu (PWD= ali Password= z vrednostjo) je napaka. Prazna vrednost ni napaka. Vrednost, ki se začne z { ali kjer koli vsebuje $, šteje za ogrado in je ukaz ne sporoči; geslo ODBC v zavitih oklepajih (PWD={s3cret}) ali geslo z znakom $ zato preverjanje prestane. Glejte Geslo je v izvornih datotekah. Absolutna pot v uporabniški profil (C:\Users\<name>\...) je opozorilo.
• Računalnik: ali COM zažene Access in ali je ta 32- ali 64-biten, kot zahteva TargetAccess; vsak sklic glede na registrirane knjižnice tipov (ista glavna različica, enaka ali višja podrejena različica, datoteka obstaja za 32- ali 64-bitno različico programa Access); vsak gonilnik ODBC, ki ga navaja profil povezave konfiguracije.

Kar ni mogoče prebrati (na primer ključ registra, za katerega nimate dovoljenja), ukaz označi kot neberljivo, nikoli kot manjkajoče. Opozorila gradnje ne ustavijo.

wkl-office build <project.acproj> [-c <name>] [--accde | --no-accde] [--json]

Zgradi build/<configuration>/<name>.accdb in, če konfiguracija tako določa, še <name>.accde. Najprej izvede check; če ta najde napako, ne ustvari ničesar. Nova podatkovna zbirka nastane v build/<configuration>/.building/ in prejšnji rezultat zamenja šele, ko so vsi koraki uspeli. Neuspela gradnja zato ohrani zadnji dobri rezultat. ACCDB in ACCDE se premakneta eno za drugo: če je prejšnja ACCDE odprta, je nova ACCDB staro že zamenjala, nova ACCDE pa ostane v .building (izhodna koda 5). Po takšnem neuspehu iz build/<configuration>/ ne pripravljajte izdaje, ampak gradite znova. Koraki gradnje so opisani v Razporeditvi in formatih izvornih datotek.

Če se koda VBA ne prevede, gradnja navede objekte, ki to povzročajo (izhodna koda 4), in pri tem ne prikaže pogovornega okna. Če je prejšnji rezultat odprt v programu Access ali v drugem programu, gradnja ne uspe s sporočilom „Podatkovna zbirka je odprta …“ in novo podatkovno zbirko ohrani v .building/ (izhodna koda 5).

wkl-office rebuild <project.acproj> [-c <name>] [--accde | --no-accde] [--json]

Odstrani ACCDB, ACCDE in delovno mapo konfiguracije ter nato gradi. Če gradnja ne uspe, od prejšnje gradnje ne ostane nič. Odprte podatkovne zbirke ukaz ne odstrani, ampak se konča z napako.

wkl-office run <project.acproj> [-c <name>] [--runtime] [--no-build] [--json]

Zgradi podatkovno zbirko (razen z --no-build) in jo odpre v vidnem programu Access, kot bi jo odprli z dvoklikom: izvedeta se njen zagonski obrazec in zagonska koda, nato pa SDK tega programa Access ne upravlja več. Z --runtime se Access zažene z /runtime in odpre ACCDE, če je bila zgrajena; brez --runtime gradnja ACCDE ne izdela. Poleg ukaza open je to edini ukaz, ki prikaže okno.

wkl-office open <project.acproj> [-c <name>] [--json]

Ta ukaz se izvede ob dvokliku na projektno datoteko v Raziskovalcu, ko povezavo nastavi addin install. open odpre prej zgrajeno podatkovno zbirko konfiguracije v vidnem programu Access, ne da bi jo znova zgradil, zato spremembe, ki ste jih naredili v programu Access in jih še niste izvozili, ostanejo ohranjene. Samo če te podatkovne zbirke še ni (svež klon), jo open najprej zgradi. Ko z ukazom git pull prenesete spremenjene vire, sami izvedite build ali rebuild (prej izvozite spremembe iz programa Access).

Podatkovna zbirka se odpre za razvoj in nič se ne zažene samodejno: zagonski obrazec in makro AutoExec se ne izvedeta, zagonske lastnosti (lasten trak, skrito podokno za krmarjenje, izklopljene posebne tipke programa Access) pa za ta zagon ne veljajo. Tako vidite podokno za krmarjenje in trak programa Access z zavihkom WKL SDK. Da je to mogoče, open pred zagonom v skritem programu Access odstrani zagonske lastnosti, AutoExec pa zamenja z nadomestnim makrom, ki samo nastavi začasno spremenljivko (TempVar); takoj ko je podatkovna zbirka odprta, open oboje obnovi. AutoExec je nato nespremenjen spet v podoknu za krmarjenje in ga lahko takoj zaženete sami. Običajni načini odpiranja podatkovne zbirke v programu Access ostanejo nespremenjeni: dvoklik na datoteko .accdb, Datoteka › Odpri in `run` zaženejo zagonski obrazec in AutoExec kot doslej.

Dokler zagonske lastnosti in AutoExec niso obnovljeni, je varnostna kopija shranjena v mapi <podatkovna zbirka>.wkl-open poleg podatkovne zbirke, na primer Stranke.accdb.wkl-open. Če se Access prej konča (zaradi zrušitve ali ker ste ga končali v upravitelju opravil), mapa ostane, podatkovna zbirka pa ima do takrat namesto vašega makra AutoExec nadomestni makro in nima zagonskih lastnosti, tudi če jo odprete z dvoklikom na datoteko .accdb. Ko SDK naslednjič dela s to podatkovno zbirko (open, export, sync, preklop projekta v dodatku), najprej obnovi prvotno stanje; tako začasno stanje nikoli ne pride v vire. Gradnja, ki podatkovno zbirko nadomesti, varnostno kopijo zavrže, ker spada k stari datoteki. Mape ne brišite sami: v njej sta vaš AutoExec in zagonske lastnosti. Če Access podatkovne zbirke po 90 sekundah še ni odprl, open izpiše opozorilo, obnovitev pa prepusti naslednjemu ukazu SDK, ki dela s to podatkovno zbirko.

Gradnja v skritem programu Access izvede kodo VBA projekta, in sicer njegovo zaključno funkcijo, ne da bi Access prikazal varnostno opozorilo, ki ga sicer pokaže ob odpiranju podatkovne zbirke. Če je projektna datoteka označena kot prenesena iz interneta (Mark of the Web; arhiv ZIP, prenesen z brskalnikom ali prejet po pošti, oznako prenese na razpakirane datoteke), open pred gradnjo zahteva potrditev. Če potrditve ne dobi (tudi kadar je standardni vhod preusmerjen), ne zgradi ničesar in se konča z izhodno kodo 8. Klon repozitorija takšne oznake nima.

Če ste open zagnali z dvoklikom in pride do napake, ostane konzolno okno odprto, dokler ne pritisnete tipke Enter, da lahko preberete sporočila. Če open zaženete iz terminala, nikoli ne čaka.

wkl-office validate <project.acproj> [-c <name>] [--json]

Preveri prej zgrajeno datoteko ACCDB: ali se projekt VBA prevede, ali so vsi sklici veljavni in ali sta v podatkovni zbirki vsaka tabela in vsak objekt iz izvornih datotek. Preverja kopijo, iz katere najprej odstrani zagonske lastnosti, zato se ne izvede noben zagonski obrazec in nobena koda traku. Podatkovno zbirko z makrom AutoExec ukaz zavrne, ker pogon podatkovne zbirke tega makra ne more izklopiti.

wkl-office accde <project.acproj> [-c <name>] [--json]

Iz prej zgrajene datoteke ACCDB izdela ACCDE. Access ne sporoči napake, kadar ACCDE ne izdela, zato ukaz potem preveri, ali datoteka obstaja; če je ni, se konča z izhodno kodo 9. Zagonske lastnosti iz AppMode zapiše samo build.

wkl-office export <project.acproj> [-c <name>] [-d <database>] [--changed] [--json]

Podatkovno zbirko zapiše v izvorne datoteke. Če je podatkovna zbirka odprta v programu Access, jo izvozi iz tega programa, sicer iz kopije v skritem programu Access. Dokler je v tem programu Access odprto pogovorno okno ali je v njem kaj neshranjenega, ukaz izvoza ne izvede in navede vsak tak objekt. Datoteko prepiše le, če se je njena vsebina spremenila. Datoteke v upravljanih mapah, katerih objekt ne obstaja več, izbriše in jih navede. Kaj izvoz zapiše in česa ne: Razporeditev in formati izvornih datotek.

wkl-office import <project.acproj> [-c <name>] [-d <database>] [--changed] [--json]

V podatkovno zbirko, odprto v programu Access, naloži poizvedbe, module, razrede, obrazce, poročila in makre, katerih izvorna datoteka se razlikuje od objekta, in doda manjkajoče sklice. Dokler je v tem programu Access odprto pogovorno okno ali je v njem kaj neshranjenega, ukaz uvoza ne izvede. Objekt, ki ga je treba zamenjati, mora biti zaprt. Ukaz ničesar ne izbriše; tabel, podatkov, relacij, lastnosti in modelov v odprti podatkovni zbirki ne spreminja. Projekta ne prevede: v programu Access uporabite Debug > Compile.

wkl-office status <project.acproj> [-c <name>] [-d <database>] [--json]
wkl-office sync   <project.acproj> [object ...] [-c <name>] [-d <database>] [--keep access|source] [--diff] [--json]

Vsako poizvedbo, modul, razred, obrazec, poročilo in makro na obeh straneh primerja z zadnjim skupnim stanjem, ki ga zapiše celoten export v obj/wkl-state.json (za vsako delovno postajo posebej, ni del repozitorija).

status ničesar ne spremeni. Ukaz ne prepiše ničesar, kar se je spremenilo na obeh straneh: dokler z --keep ne odločite, katera stran velja, se izvajanje zaradi takšnih objektov konča z izhodno kodo 7. Če v ukazu za projektno datoteko navedete še objekte (form:frmStranke, module:basLists ali ključe, ki jih izpiše changes --json), sync omejite nanje: še vedno primerja in navede vse objekte, prenese pa samo navedene oziroma odloči samo o njih. Tako lahko o sporih odločate enega za drugim. Če navedenega imena ni ne v podatkovni zbirki ne v izvornih datotekah, se ukaz konča z izhodno kodo 5 in ne spremeni ničesar. Preimenovanje se prenese kot preimenovanje samo, če ima staro besedilo natanko en objekt iste vrste. Za prenos sprememb v podatkovno zbirko mora biti ta odprta v programu Access. Tabel, podatkov, relacij, sklicev, lastnosti in modelov ukaz ne spremlja po objektih: zapiše jih celoten export, ustvari pa build.

wkl-office changes <project.acproj> [-c <name>] [-d <database>] [--json]

Projekt preveri takoj ob klicu in v eni tabeli navede vsak objekt ali izvorno datoteko, ki ni usklajena. Tri primerjave so prikazane ločeno, ker vsaka zahteva drug korak:

Naslednji korak v vrstici izhaja iz prvih dveh stolpcev, v tem vrstnem redu:

Prva vrstica navede čas preverjanja. Če del preverjanja ni uspel (Access se ni odzval ali je nadzor različic sporočil napako), se prva vrstica glasi NI AŽURNO in navede, kaj ni uspelo; izhodna koda je 5. Seznam je tedaj lahko nepopoln in ga nikoli ne smete razumeti kot „ni sprememb“. Vrstica veje uporablja to, kar je prineslo zadnje pridobivanje (fetch); changes z oddaljenim repozitorijem ne vzpostavi stika.

wkl-office diff <project.acproj> <object | file> [--against access|git] [--part design|code] [-c <name>] [-d <database>] [--json]

Izpiše celotno razliko enega objekta ali ene izvorne datoteke v poenotenem formatu, vsako spremenjeno vrstico s tremi vrsticami sobesedila. Objekt navedite tako kot changes --json (form:frmStranke, module:basLists), izvorno datoteko pa relativno glede na projekt (source/forms/frmStranke.form.txt); zadošča konec poti, če je enoličen.

• --against access primerja izvorno datoteko (staro) z besedilom, ki ga ima Access zdaj (novo), torej s tem, kar bi zapisal izvoz.
• --against git primerja zadnji commit (staro) z izvorno datoteko (novo), torej s tem, kar bi zabeležil commit.
• --part code obdrži samo modul obrazca ali poročila (od CodeBehindForm naprej), --part design pa samo preostanek.

Brez --against se objekt, ki se v programu Access in v izvorni datoteki razlikuje, primerja s programom Access, vse drugo pa z zadnjim commitom. Če sta besedili enaki, ukaz izpiše ni razlike.

wkl-office commit <project.acproj> -m <message> [<file> ...] [-c <name>] [-d <database>] [--json]

Najprej znova preveri stanje, tako kot changes. Če katera od vrstic zahteva import, odloči ali razreši konflikt spajanja ali če preverjanje ni uspelo, commit zavrne z izhodno kodo 7, ne da bi kar koli zapisal: celoten izvoz bi sicer prepisal izvorno datoteko, spremenjeno zunaj programa Access, ali pa potrdil le pol spajanja. Nato izvozi (dokler je kaj neshranjeno, izvoz zavrne) ter projektno datoteko, njen .gitignore in mapo z izvornimi datotekami preda odjemalcu za nadzor različic, ki ga najde v PATH (git ali svn; odloči najbližja delovna kopija nad projektom) in jih potrdi. Datoteke, ki jih je izvoz odstranil, se izbrišejo tudi v nadzoru različic. Drugih datotek v delovni kopiji se ukaz ne dotakne in ničesar ne pošlje v oddaljeni repozitorij. Če so izvorne datoteke enake potrjenim, ne potrdi ničesar.

Če za projektom navedete datoteke (poti relativno glede na mapo projekta, na primer source/forms/frmStranke.form.txt), se potrdijo samo te: to je delni commit. Preverjanje in izvoz kljub temu zajameta celoten projekt, zato vrstica, ki zahteva import, commit ustavi, tudi če njene datoteke niste navedli. Nenavedene datoteke ostanejo v delovni kopiji spremenjene za poznejši commit. Navesti smete samo projektno datoteko, njen .gitignore in datoteke pod korensko mapo izvornih datotek; vsako drugo datoteko ukaz zavrne z izhodno kodo 1, še preden kar koli stori. Izbrisano izvorno datoteko navedete kot vsako drugo in se potrdi kot izbris.

wkl-office push <project.acproj> [--json]

Za vejo delovne kopije izvede git push in izpiše, kar je izpisal git. Ukaz nikoli ni del ukaza commit: objava spremembe ostaja vaša ločena odločitev. V delovni kopiji Subversion ni ničesar za pošiljanje, kar ukaz tudi sporoči.

wkl-office addin install | remove | status [--json]

Razvijalski dodatek SDK za trenutnega uporabnika registrira (pravice skrbnika niso potrebne), ga odstrani ali sporoči njegovo stanje. install vzame dodatek v 32- ali 64-bitni različici, kot ustreza nameščenemu programu Access, iz mape addin poleg mape bin SDK ali iz mape, ki jo navaja spremenljivka okolja WKL_OFFICE_ADDIN. Poleg tega install iz mape bootstrapper-manager ob tej mapi dodatka kopira program Bootstrapper Manager v %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager\<version>, če ta različica še ni nameščena; remove ga pusti nameščenega. Gradnja dodatka nikoli ne registrira, to stori samo ta ukaz.

install za trenutnega uporabnika z SDK poveže tudi projektne datoteke (.acproj). Dvoklik v Raziskovalcu izvede `open`, v meniju projektne datoteke pa se pojavi podmeni „WKL Office SDK“ z ukazi Odpri, Zgradi in zaženi, Preveri, Zgradi in Znova zgradi (ukazi open, run, check, build in rebuild); v sistemu Windows 11 je pod „Pokaži več možnosti“. Ukazi uporabljajo datoteko wkl-office.exe, s katero ste izvedli namestitev, zato jih namestitev nove različice preusmeri nanjo. Windows nobenemu programu ne dovoli, da bi se sam nastavil kot privzeti: ob prvem dvokliku na datoteko .acproj vas enkrat vpraša, s katero aplikacijo naj jo odpre; izberite „WKL Office SDK“ in „Vedno“. Dokler izbire ne opravite, vas install na to opozori. Podmeni je na voljo ne glede na to, s katerim programom se datoteka odpira. Projektne datoteke prikazujejo ikono programa Access. Če je .acproj že povezana z drugim programom, ostane povezana z njim, SDK pa je naveden le pod „Odpri z“. Po ukazih Preveri, Zgradi in Znova zgradi okno ostane odprto, dokler ne pritisnete tipke Enter, po ukazih Odpri ter Zgradi in zaženi pa le ob napaki. remove povezavo in podmeni odstrani, status sporoči stanje obeh (projectFiles in projectFilesChosen v JSON).

install dodatek vpiše tudi za urejevalnik VBA nameščenega sistema Office, za vsakega uporabnika pod HKEY_CURRENT_USER\Software\Microsoft\VBA\VBE\6.0\Addins (pri 64-bitnem sistemu Office pod Addins64), da ga urejevalnik naloži, ko ga odprete; remove vpis odstrani, status pa sporoči njegovo stanje (editorListed in editorLoadBehavior v JSON).

Dodatek se naloži ob naslednjem zagonu programa Access. Glejte Uporaba dodatka za Access.

wkl-office settings list | get <key> | set <key> [<value>] [--json]

Prikaže in spremeni nastavitve SDK trenutnega uporabnika (%APPDATA%\WKL\Office SDK\settings.json), tako kot Nastavitve v dodatku. list prikaže vse nastavitve, get eno, vsako z vrednostjo, ki velja, in njenim izvorom: default, settings ali environment z imenom spremenljivke. set zapiše vrednost; brez vrednosti vnos odstrani, nato pa spet velja privzeta vrednost. Če zapisano vrednost preglasi spremenljivka okolja, set na to opozori. Pri neznani nastavitvi ali neustrezni vrednosti se ukaz konča z izhodno kodo 1, z izhodno kodo 3 pa, če datoteke z nastavitvami ni mogoče prebrati ali zapisati; datoteka takrat ostane nespremenjena.

wkl-office roundtrip <project.acproj> [-c <name>] [--json]

Krožna preverba kopira projekt v začasno mapo, zgradi kopijo, jo izvozi v to kopijo in rezultat primerja z izvornimi datotekami. Besedilne datoteke primerja s poenotenimi konci vrstic, pri vseh drugih šteje vsak bajt. Vsako datoteko z razlikami navede kot changed: <path>:<line>, added: <path> ali removed: <path>, kopijo ohrani za primerjavo in se konča z izhodno kodo 6. Poti datotek, ki se razlikujejo, so relativne glede na mapo projektne datoteke (changed: source/forms/frmA.form.txt:3). Zaženite jo na izvornih datotekah, ki jih je zapisal export: prvi izvoz po migrate datoteke enkrat prepiše. Izhodna koda 0 pomeni, da so izvorne datoteke stabilne: izvoz zgrajene podatkovne zbirke zapiše natanko iste izvorne datoteke. Ne pomeni pa, da izvorne datoteke vsebujejo vse, kar je imela prvotna podatkovna zbirka, niti da se aplikacija obnaša enako (glejte Česa izvoz ne ohrani). Kopija se zgradi brez ACCDE in s profilom povezave konfiguracije; opozorila izvoza ne povzročijo neuspeha krožne preverbe.

VBA vodi za vsak identifikator v celotnem projektu en sam zapis velikih in malih črk, tudi prek modulov predloge in imen knjižnic v sklicih. Ko se zgrajena podatkovna zbirka prevede, se Static done As Boolean spremeni v Static Done As Boolean, če je Done drugje zapisan tako. roundtrip tedaj javi changed: v modulu, ki ga ni nihče spremenil. Uporabite zapis, ki ga zapiše izvoz, ali identifikator preimenujte.

wkl-office migrate <old.acproj | access-app.json> -o <folder> [--json]

Projekt pretvori v nov projekt v mapi <folder>, ki mora biti prazna ali še ne sme obstajati. Vsako nastavitev, ki v novem projektu nima mesta, izpiše kot opombo. Zažene skriti Access, da prebere stare definicije tabel (DATEC) ali izvede skripte SQL (orodje za gradnjo). Glejte Selitev projekta DATEC Access SDK in Selitev projekta orodja za gradnjo WKL Forms Object Library.

wkl-office migrate <project.acproj | access-app.json> [--whatif] [--json]

Brez -o ukaz projekt v njegovi mapi prenese z WKL Forms Object Library 1.x (knjižnica tipov WklComponents) na 2.0 (WklForms), brez programa Access. V izdaji 2.0 sta knjižnica tipov in njeni ProgID-ji dobili nova imena, ID-ji razredov pa so ostali enaki. Obrazci zato obdržijo svoje kontrolnike, spremeni pa se vsako mesto, ki navaja knjižnico:

• sklic v source/references.json (ali v references datoteke access-app.json): ime WklForms, glavna različica 2, podrejena različica 0;
• ime WklComponents kot cela beseda v vsaki drugi besedilni datoteki projekta: moduli, obrazci in poročila (Class ="WklComponents.TreeView"), poizvedbe, makri, trakovi, modeli (WklComponents.Texts postane WklForms.Texts);
• packages.components v delivery/delivery-settings.json, kadar navaja paket izdaje 1.x: najnovejši paket izdaje 2.0 ali novejše pod WKL_PACKAGES; če ga ni, vnos ostane, z opombo.

Datoteke obdržijo kodiranje, oznako vrstnega reda bajtov in konce vrstic. Dokumentacije (*.md) in podatkov tabel (source/data) ukaz ne spreminja, ampak jih le navede v opombi. Ukaz preskoči mape build, out, obj, bin in vsako mapo, katere ime se začne s piko (.git, .vs). Vsaka spremenjena datoteka se izpiše kot changed: <file> (<count>) s spremenjenimi vrsticami; --whatif izpiše would change: in ničesar ne zapiše. Ukaz zaženite enkrat, projekt zgradite z registrirano izdajo 2.0 in ga potrdite. Glejte WKL Forms Object Library, „Prehod aplikacije na izdajo 2.0“.

wkl-office deliver <project.acproj> [-p <name>] [--version <x.y.z>] [--dependencies] [--whatif] [--json]

Pripravi izdajo za profile izdaje projekta (referenčni priročnik), za vsakega posebej: v obliki 2 za vsako datoteko delivery\<name>.profile.json, urejeno po imenu, v obliki 1 za vsak cilj iz delivery\delivery-settings.json, poimenovan po svojem načinu. Podatkovno zbirko zgradi v konfiguraciji gradnje profila v skritem programu Access (ACCDE z zagonskimi lastnostmi načina, ki ga določa konfiguracija; za način Development ACCDB) in nato zapiše build\Delivery\<name>:

build\Delivery\production\
  Wkl.Bootstrapper.exe               the starter, from the bootstrapper release named in delivery-settings.json
  bootstrapper.json                  the starter's project file, a copy of delivery\production.bootstrapper.json
  deploy\
    <name>.accde                     the built database
    app-manifest.json                product, version, target, file, SHA-256, size, bitness, runtime, requires, built
    components\x86\, components\x64\  WKL Forms Object Library from its release package, when the project references it
    json\x86\, json\x64\              WKL Office JSON, when the project references it

Drugo mapo izdaje za posamezen profil določite z output v datoteki profila (oblika 1: targets[].output v delivery-settings.json; absolutno, s spremenljivkami okolja ali relativno glede na mapo projekta). Mapa se vsakič zapiše na novo; mapo, izbrano z output, SDK izprazni le, če jo je zapisala že prejšnja izdaja. Če datoteka delivery\<name>.bootstrapper.json manjka, jo zapiše zaganjalnik iz svojih predlog (access, components, json) in ostane med izvornimi datotekami; urejate jo s programom Bootstrapper Manager. Zaganjalnik jo nato preveri (/check). requires navaja različico, ki jo Access ob gradnji zapiše v podatkovno zbirko: najvišjo različico z glavno različico sklica, ki je registrirana na računalniku za gradnjo. Vsak vnos navaja tudi identifikator LIBID knjižnice tipov (guid): po njem zaganjalnik od različice WKL Bootstrapper 3.2 naprej prepozna knjižnico, starejši zaganjalniki pa ga prezrejo. Če priprava enega profila ne uspe, se ukaz ustavi in naslednjih profilov ne zgradi niti ne pripravi. Če izdaje ni bilo mogoče sestaviti (paket, zaganjalnik ali njegova projektna datoteka), se ukaz konča z izhodno kodo 11; napake gradnje ohranijo svoje kode. Glejte Priprava izdaje aplikacije z WKL Office SDK.

wkl-office msi <project.acproj> -p <name> [--version <x.y.z>] [--sign <thumbprint>] [--json]

Za profil, za katerega je izdaja že pripravljena, zgradi namestitveni paket Windows Installer s skriptom tools\New-StarterMsi.ps1 iz izdaje zaganjalnika (bootstrapper). Paket vsebuje zaganjalnik in njegovo projektno datoteko iz build\Delivery\<name>; služba IT ga na vsak računalnik namesti enkrat. Potrebuje ukazno vrstico WiX Toolset (wix), za --sign pa še signtool.exe iz Windows SDK. Če izdaja za profil ni pripravljena, če orodje manjka ali ni uspelo, se ukaz konča z izhodno kodo 11 in izpiše izhod orodja.

wkl-office call <project.acproj | database> <function> [argument ...] [-c <name>] [-t accdb|accde] [--work <folder>] [--timeout <s>] [--json]

Pokliče javno funkcijo standardnega modula v zgrajeni podatkovni zbirki in izpiše njeno vrnjeno vrednost. Tako lahko skript ali preizkus uporabi kodo aplikacije, ne da bi jo odprl. Pri projektni datoteki je podatkovna zbirka build\<configuration>\<name>.accdb (z -t accde datoteka .accde); datoteko podatkovne zbirke (.accdb, .accde) ukaz uporabi tako, kot je navedena. call ne gradi, zato najprej izvedite build.

Funkcija se izvede v skritem programu Access na kopiji podatkovne zbirke:

• Iz kopije se najprej odstranijo zagonske lastnosti, zato se ne zažene ne zagonski obrazec ne povratni klic traku ne makro AutoExec. Zbirko z makrom AutoExec ukaz zavrne (izhodna koda 5). Če funkcija potrebuje pripravo, ki jo sicer opravi zagonski obrazec, mora to kodo poklicati sama.
• Sama podatkovna zbirka ostane nespremenjena. Kopija nastane v začasni mapi, ki se nato izbriše; z --work <folder> nastane v tej mapi in tam ostane, skupaj z vsem, kar je funkcija zapisala vanjo.
• {work} v argumentu se nadomesti s polno potjo mape s kopijo (tudi začasne): wkl-office call app.acproj ExportOrders "{work}\orders.csv" --work out.
• Argumenti se predajo kot besedilo. VBA jih pretvori, kadar funkcija parameter deklarira kot ByVal ... As Long, ByVal ... As Date ipd.; pri parametru ByRef drugega tipa kot String ali Variant Access klic zavrne. Največ 30 argumentov. Argumenti, ki se začnejo s pomišljajem, morajo slediti --: wkl-office call app.acproj Twice -- -5.
• SDK programu Access ne predaja spremenljivk okolja. Ali Access, zagnan na ta način, vidi spremenljivke klicočega procesa, je odvisno od tega, kako ga zažene Windows (v sistemu Windows 11 jih vidi); funkcija se na to ne sme zanašati. Takšne vrednosti predajte kot argumente.

Vrnjena vrednost se izpiše na standardni izhod: besedilo nespremenjeno, števila z decimalno piko, True ali False, datum kot yyyy-MM-dd (s THH:mm:ss, če vsebuje čas), Null za Null, nič za Empty, elementi polja pa vsak v svoji vrstici.

Na pogovorna okna ukaz odgovori brez tipkovnice: na pogovorno okno napake VBA z gumbom Končaj (End), na vsa druga s tipko Escape in, če okno ostane odprto, z gumbom Prekliči, Ne ali V redu. Access pogovorno okno napake VBA ali okno s sporočilom prikaže na namizju tudi takrat, ko teče skrito; okno izgine po približno sekundi. Funkcija, namenjena za call, naj zato svoje napake obravnava sama in ne prikazuje pogovornih oken.

wkl-office test <project.acproj> [-c <name>] [-t accdb|accde] [--only <names>] [--timeout <s>] [--work <folder>] [--no-build] [--no-count-guard] [--language <code>] [--json]

Zgradi konfiguracijo (razen z --no-build; z -t accde tudi ACCDE) in nato v skritem programu Access izvede preizkusne postopke aplikacije na kopiji podatkovne zbirke v delovni mapi (privzeto build\<configuration>\test). Projekt navede svojo preizkusno funkcijo v <Test> (projektna datoteka); ta vrne imena preizkusnih postopkov. Kako jih napišete, opisuje stran Preizkušanje aplikacije.

Vsak postopek se izvede posebej, s časovno omejitvijo iz --timeout (privzeto 120 sekund):

• Njegova preverjanja (WklTest.Check) se izpišejo kot OK <procedure>: <check> ali FAIL <procedure>: <check> :: <message>. Postopek, ki se konča brez lastnega preverjanja, šteje za eno uspešno vrstico.
• Napaka med izvajanjem, ki je postopek ne obravnava, je neuspešna vrstica z besedilom napake VBA; izvajanje se nadaljuje z naslednjim postopkom.
• Na pogovorno okno, ki ne gre prek WklTest.Answer, ukaz odgovori kot pri `call`, postopek pa ne uspe.
• Če postopek preseže časovno omejitev, se njegov Access konča in izvajanje se ustavi.
• Če se Access med postopkom konča (sesutje), se izvajanje ustavi s sporočilom „Access ended“ in navede zadnjo zapisano vrstico.

V delovni mapi ostanejo kopija, wkl-test-run.jsonl (vrstica za vsako preverjanje, zapisana takoj, zato vrstice pred sesutjem ostanejo) in wkl-test-report.xml (JUnit XML za strežnike CI, en preizkusni primer za vsako preverjanje). Izpis se konča z vrstico povzetka: <n> OK, <m> FAIL (preizkusni postopki: <k>).

Varovalo števila preverjanj. Če ima izvajanje vseh postopkov manj preverjanj kot zadnje uspešno izvajanje iste konfiguracije, istega cilja in istega jezika, ne uspe z vrstico check count. Tako opazite preizkuse, ki se po pomoti ne izvajajo več. Števila so shranjena v obj\wkl-test-count.json; z --only se varovalo preskoči, z --no-count-guard pa izklopi.

Jezik. --language <code> (katera koli koda jezika, na primer de ali fr; regionalna koda, na primer sl-SI, šteje kot njen jezik) izvede postopke z besedili aplikacije in komponentami WKL v tem jeziku, ne glede na jezik Officea: SDK na začetku izvajanja enkrat nastavi WklTexts.Language. Zahteva WKL Forms Object Library 1.65 ali novejšo različico, koda, ki ni en, de, sl, hr ali it, pa 1.67 ali novejšo; s starejšo se izvajanje ustavi z izhodno kodo 2.

wkl-office texts export <project.acproj> [<file.csv>] [--language <code>]
wkl-office texts import <project.acproj> [<file.csv> ...] [--replace]

Besedila aplikacije v projektu (source/texts/*.json, oblika) izmenja z datotekami CSV, ki jih Excel odpre neposredno. Access ni potreben.

• export za vsak ključ katerega koli jezika zapiše vrstico s stolpcem key, nato s po enim stolpcem za vsak obstoječi jezik, najprej neutral (key,neutral,de,fr); privzeta datoteka je texts.csv poleg projektne datoteke. Prazna celica pomeni „v tem jeziku ni besedila“.
• export --language <code> namesto tega zapiše paket za prevod enega jezika (privzeto texts.<code>.csv): za vsak ključ aplikacije vrstico s stolpci key, source (nevtralno besedilo, sicer angleško), stolpcem jezika in review (pri prevodu, označenem za pregled, izvirno besedilo, iz katerega je nastal). Za neutral paketa ni.
• import v poljubnem vrstnem redu združi eno ali več datotek CSV, pakete ali celotne izvoze (privzeto texts.csv). Zapišejo se le stolpci jezikov, source in review pa ne. Prazna celica in manjkajoča vrstica ne spremenita ničesar, noben ključ se ne odstrani. Ključ, ki ga aplikacija nima, se preskoči z opozorilom; novi ključi prihajajo le iz stolpca neutral (oziroma en v projektu brez nevtralnih besedil). Če dve datoteki za isti ključ in isti jezik navajata različni besedili, se ne zapiše nič. Prevod, katerega source se razlikuje od trenutnega nevtralnega besedila, in vsak prevod ključa, katerega nevtralno besedilo uvoz spremeni, se v source/texts/review.<code>.json označi za pregled. Za vsak jezik ena vrstica navede, koliko besedil je novih, spremenjenih, še neprevedenih in označenih za pregled.
• import --replace <file.csv> sprejme natanko eno datoteko CSV kot celoten nabor: ključ, ki ga v njej ni, se odstrani. Če je stolpec jezika prazen v vseh vrsticah, datoteka tega jezika ostane nespremenjena. Za vsak jezik ena vrstica navede število besedil ter koliko jih je novih, spremenjenih in odstranjenih.
• Vse datoteke so v kodiranju UTF-8; export zapiše oznako vrstnega reda bajtov, vejice in CR LF, import pa prebere datoteke, ločene z vejicami ali podpičji, kot jih Excel shrani glede na področne nastavitve sistema Windows. Vsaka datoteka z besedili se zapiše v kanonični obliki, vendar le, če se njena vsebina spremeni.
• Izhodna koda 2, če datotek z besedili ali datoteke CSV ni mogoče prebrati (ni naslovne vrstice, ki se začne s key, stolpec, ki ni koda jezika niti neutral, source ali review, ključ dvakrat), če si datoteke nasprotujejo ali če datoteka CSV pri --replace nima niti nevtralnih niti angleških besedil. Izhodna koda 1 za --replace z več kot eno datoteko.

Kode, ki jih posamezen ukaz uporablja poleg 0, 1 in 10:

Z --json ukaz namesto besedila izpiše na standardni izhod en objekt JSON. Izjeme:

• Če je klic napačen (izhodna koda 1), se na standardni izhod za napake izpiše, kaj je narobe; JSON se ne izpiše. Tudi new in addin z neznanim dejanjem se končata z izhodno kodo 1, vendar izpišeta svoj JSON; commit z datoteko zunaj projekta izpiše vrstico error: na standardni izhod za napake, brez navodil za uporabo in brez JSON (izhodna koda 1).
• diff --against access izpiše besedilo, če sta Access in izvorna datoteka objekta usklajena (izhodna koda 0) ali če preverjanje ni uspelo (izhodna koda 2).
• Po Ctrl+C se na standardni izhod za napake izpiše samo sporočilo o preklicu (izhodna koda 8).

Polja so odvisna od ukaza:

Brez --json se težave izpišejo kot <severity> [<phase>] <object>, <file>: <cause>; prazen del se izpusti. Z --format msbuild je vsaka težava vrstica <file>(<line>): <error|warning> WKL<nnn>: <object>: <cause> s polno potjo, ki jo Visual Studio Code in drugi urejevalniki pokažejo na pravem mestu. Številka označuje fazo, enako kot v opravilih MSBuild:

• Brez pogovornih oken. Razen run in open noben ukaz ne prikaže lastnega okna. Access teče skrito. Pogovorno okno, ki ga prikaže med korakom, se zabeleži z besedilom in prekliče s tipko Esc, korak pa ne uspe. V programu Access, ki ste ga odprli sami (glejte spodaj), to velja za pogovorno okno, ki se odpre med korakom; okna, ki so bila odprta že prej, ostanejo.
• Časovne omejitve. Vsak korak ima stalno časovno omejitev, ki je ni mogoče spremeniti: 60 sekund za večino korakov, 90 za premik enega objekta, 120 za modele, izvoz in odpiranje kopije, 180 za prevajanje in izdelavo ACCDE ter 5 minut za podatke ene tabele in za zaključno funkcijo. Časovne omejitve in nadzor pogovornih oken veljajo za korake v programu Access. git in svn tečeta tako kot v ukazni vrstici, brez časovne omejitve, zato lahko poziv za poverilnice, okno upravitelja poverilnic ali kavelj (hook) ustavi commit ali push. Na računalnikih za gradnjo zato nastavite preverjanje pristnosti, ki ne zahteva vnosa. Ko korak v skritem programu Access preseže svojo omejitev, se ta Access takoj konča in korak ne uspe. Koraka v programu Access, ki ste ga odprli sami, SDK ne prekine: počaka, da se Access odzove, in nato sporoči, da je korak trajal dlje od svoje omejitve.
• Noben Access ne ostane odprt. Vsak Access, ki ga zažene SDK, se ob koncu izvajanja konča: najprej ga SDK pozove, naj se zapre, in ga prisilno konča šele po 30 sekundah (kar sporoči). Če je wkl-office prisilno končan ali se sesuje, Windows konča tudi njegov Access, ker ga SDK uvrsti v objekt opravila (job object); če Windows tega ne bi dovolil, kar doslej ni bilo opaženo, ta varovalka manjka. Windows Access zažene prek COM, SDK pa ga v objekt opravila uvrsti, takoj ko se Access odzove, v približno sekundi. Če je wkl-office prisilno končan v tem prvem trenutku, njegov Access teče naprej in ga morate zapreti ročno. Ctrl+C pozove Access tega izvajanja, naj se zapre, ukaz pa se takoj konča z izhodno kodo 8. Programa Access, ki ste ga odprli sami, SDK nikoli ne zapre.
• Po prekinjenem izvajanju (Ctrl+C, prisilno končan proces, časovna omejitev): export pusti datoteke, ki jih je že zapisal, morda eno okrnjeno, ne izbriše zastarelih datotek in ne zapiše skupnega stanja. sync skupno stanje zapiše šele na koncu, zato so objekti, ki jih je že prenesel, prikazani kot spremenjeni na obeh straneh. build pusti mapo .building, ki jo naslednja gradnja odstrani. commit lahko pusti datoteke v pripravljalnem območju, ne da bi bile potrjene. import v programu Access, ki ste ga odprli sami, pusti objekte, ki jih je že naložil. Zaženite wkl-office changes. Po prekinjenem izvozu ali sinhronizaciji izvedite celoten wkl-office export, ko ima Access želeno stanje, ali pa o vrsticah odločite s sync --keep. Po prekinjeni gradnji gradite znova, po prekinjenem commitu pa preverite git status in znova zaženite commit.
• Podatkovna zbirka, odprta v programu Access. export, import, status, sync in commit poiščejo Access, ki ima podatkovno zbirko odprto, prek tabele Running Object Table po celotni poti podatkovne zbirke (velike in male črke se ne razlikujejo) in delajo v njem. Tudi changes in diff pogledata tja. SDK najde le Access, ki ga je zagnal isti uporabnik, ne pa programa Access, zagnanega s skrbniškimi pravicami. Takšnega programa Access SDK nikoli ne zapre ali konča, tudi ne, kadar korak traja dlje od svoje časovne omejitve.
• Gostitelj terminala. wkl-office terminal-host uporablja terminal dodatka in ni namenjen ročnemu klicanju.
• 32- in 64-bitni Office. Orodje upravlja Access od zunaj, kot ločen proces, zato ena namestitev deluje z 32- in 64-bitno različico sistema Office.

• Pregled
• Referenčni priročnik projektne datoteke
• Razporeditev in formati izvornih datotek
• Odpravljanje težav