Een aangepast besturingselement registreren

Doel

Een aangepast besturingselement in een omgeving installeren door zijn pakket te uploaden, zodat het op een veld van een modelgestuurd formulier kan worden geplaatst.

Zoek je hoe je het besturingselement bouwt in plaats van hoe je het installeert? Deze pagina gaat ervan uit dat het besturingselement al bestaat en is verpakt. Het schrijven ervan — het vaste props-contract, welke veldtypen het kan vervangen, de waardetoestanden die het moet afhandelen, testen en verpakken — staat in Een aangepast besturingselement bouwen.

Vereisten

• Je bent als platformbeheerder aangemeld bij het Beheercentrum.
• Er bestaan al een uitgever en een oplossing die eigendom is van die uitgever.
• De omgeving waarin je het besturingselement installeert, is actief.
• Je hebt het pakket van het besturingselement — de .zip die npm run pack in het eigen project van het besturingselement maakt. Dat wordt meestal in de map package/ van dat project geschreven en naar het besturingselement genoemd, bijvoorbeeld par_signature_pad-1.2.3.zip.

Stappen

1. Kies de omgeving waarin het besturingselement moet worden geïnstalleerd, met de kiezer in de bovenbalk.
2. Open Oplossingen en open daarna de oplossing waar het besturingselement bij hoort.
3. Selecteer Aangepaste besturingselementen in de linkernavigatie van de oplossing (of de kaart Aangepaste besturingselementen op het overzicht van de oplossing). De pagina toont de besturingselementen die deze oplossing al in de geselecteerde omgeving heeft geïnstalleerd.
4. Selecteer Nieuw. Aan de zijkant van het scherm opent een deelvenster.
5. Kies het pakketbestand van het besturingselement.
6. Selecteer Aangepast besturingselement registreren. Het besturingselement verschijnt in de lijst voor die oplossing en omgeving, op het overzicht van de oplossing onder Aangepaste besturingselementen, en in het veldenpalet van de formulierontwerper.

Dat is het hele formulier. Er valt verder niets in te vullen, omdat het pakket het allemaal al zegt: de logische naam en de weergavenaam van het besturingselement, de Module Federation-scope en de beschikbaar gemaakte module die de build werkelijk heeft gebruikt, het invoerbestand dat moet worden geleverd, en de veldtypen die het kan vervangen. Die laatste twee werden vroeger met de hand uit een bundlerconfiguratie overgenomen, en als een van beide niet klopte, gaf dat één symptoom — het besturingselement laadde gewoon niet — zonder dat iets zei welke van de twee fout was.

Opnieuw uploaden vervangt de geïnstalleerde build. Dat is de normale cyclus terwijl je aan een besturingselement werkt: wijzigen, npm run pack uitvoeren, opnieuw uploaden. Je hoeft de oude registratie niet eerst weg te halen. De kolom Versie toont welke build is geïnstalleerd, zodat je kunt controleren of wat er draait, ook is wat je het laatst hebt verpakt.

Om een besturingselement weg te halen, vink je de rij aan en selecteer je Weghalen. Dat verwijdert het uit de omgeving en verwijdert het opgeslagen pakket; de oplossing houdt haar verwijzing naar het component, omdat het besturingselement in andere omgevingen nog geïnstalleerd kan zijn.

Waar de code van het besturingselement staat

De bytes van het pakket worden door het platform opgeslagen en geleverd vanaf het eigen adres van het platform. Er wordt niets van een externe host opgehaald, dus:

• is de oplossing op zichzelf compleet — bij het exporteren gaat de code van het besturingselement mee, en importeren in Test of Productie installeert een werkend besturingselement in plaats van een verwijzing naar de plek waar het is gebouwd;
• is er geen URL om op de allowlist te zetten, en geen URL die kan verouderen.

De code van een besturingselement hoeft niet als webresources te worden geüpload. Webresources zijn voor losse bestanden die je zelf maakt en bij naam aanroept — een stijlblad, een afbeelding, een script — niet voor de build-uitvoer van een besturingselement.

Wat er achter de schermen gebeurt

Het archief wordt gecontroleerd voordat er iets wordt opgeslagen: de grootte, hoeveel bestanden erin zitten en hoe groot het uitgepakt wordt, dat geen bestand erin een pad buiten zijn eigen map noemt, dat elk bestand van een type is dat het platform levert, en dat het manifest overeenkomt met het gepubliceerde pakketschema. Daarna wordt de logische naam van het besturingselement gecontroleerd tegen het voorvoegsel van de uitgever die eigenaar is.

Het pakket wordt in zijn geheel opgeslagen en uitgepakt op het moment dat het besturingselement voor het eerst echt wordt opgevraagd. Daarom blijft een besturingselement werken nadat het platform opnieuw is gestart, en werkt het op elke server hetzelfde: het opgeslagen pakket is het echte exemplaar, en de uitgepakte bestanden zijn alleen een cache die zichzelf opnieuw opbouwt.

Een besturingselement in de ene omgeving installeren, installeert het niet in een andere; het reist mee wanneer zijn oplossing wordt geëxporteerd en geïmporteerd.

Problemen oplossen

• "The package has no 'parsware.json' at its root." — het geüploade bestand is gewone build-uitvoer in plaats van een pakket. Bouw het met npm run pack in het project van het besturingselement.
• "Custom control … must start with the publisher prefix …_." — de logicalName in de package.json van het besturingselement begint niet met het voorvoegsel van de uitgever die eigenaar is. Pas het daar aan en verpak opnieuw.
• "The package holds … files; the maximum is …" — bijna altijd een map node_modules die in het archief terecht is gekomen. Verpak de build-uitvoer, niet het project.
• "Custom control … is already installed in this environment by another solution." — de logische naam is al in gebruik. Geef het besturingselement een andere naam, of haal de andere registratie weg.
• "Environment … is not active." — wacht tot de omgeving klaar is met inrichten, of kies een andere omgeving.

Terwijl je het besturingselement schrijft

Voor elke wijziging een pakket uploaden is een trage lus. In een ontwikkelomgeving biedt Nieuw een tweede keuze, Een draaiende ontwikkelserver gebruiken: typ het adres dat npm run dev toont en kies Aangepast besturingselement registreren. De naam van het besturingselement en de federation-instellingen worden van de ontwikkelserver gelezen, en formulieren laden het besturingselement daarvandaan, dus een opgeslagen wijziging zie je de volgende keer dat een formulier opent. De kolom Versie toont Gehost (ontwikkeling) zolang het zo geregistreerd is.

• Is het besturingselement al geïnstalleerd, verwijder het dan eerst. Een ontwikkelserver wordt geregistreerd onder de logische naam van het besturingselement, dus het formulier waaraan je het koppelde, blijft het gebruiken.
• Ben je klaar, upload dan het pakket. Dat vervangt de registratie van de ontwikkelserver, en de kolom Versie toont weer de build.

Buiten een ontwikkelomgeving verschijnt de keuze niet: een besturingselement dat zo is geregistreerd, heeft geen pakket, dus de code zou niet met de oplossing meereizen. Hoe je het project daarvoor inricht, staat in Een aangepast besturingselement bouwen.

Gerelateerde scenario's

• Een aangepast besturingselement bouwen.
• Een aangepast besturingselement aan een veld koppelen.
• Een aangepaste React-app registreren.
• Een oplossing maken.