Eine REST-API aus der Visual-FoxPro-IDE mit FoxServer veröffentlichen

Ich habe in der FoxPro-Community, auf Patreon und in der WhatsApp-Gruppe, eine Umfrage mit einer einzigen Frage gemacht: Was ist heute das Schwierigste an Ihrer VFP-Anwendung? Zwei von drei antworteten dasselbe: sie im Web oder als API bereitzustellen. Die Daten und die Logik, die sie bereits haben, in etwas zu bringen, das ein Browser, eine mobile App oder ein Programm einer anderen Firma aufrufen kann.

Dieses Tutorial ist die Antwort auf diese Frage, und zwar aus der Visual-FoxPro-IDE, der altbekannten. Am Ende haben Sie eine REST-API, die eine DBF-Tabelle als JSON zurückgibt und neue Datensätze annimmt. Der Code ist ganz normales VFP 9, und Sie fassen die Anwendung, die Sie bereits haben, nicht an: Sie veröffentlichen sie.

Ich fange bei null an: Visual FoxPro ist geschlossen. Jeder Schritt sagt, was Sie anklicken, was Sie schreiben und was Sie auf dem Bildschirm sehen müssen. Wenn das, was Sie sehen, irgendwann nicht dem Screenshot ähnelt, halten Sie dort an: Direkt darunter erkläre ich, warum das passiert und wie man es behebt.

Sind Sie auf der Kommandozeile mehr zu Hause? Es gibt dasselbe Tutorial als CLI-Version: dasselbe Projekt, dasselbe Ergebnis, mit Befehlen, die man in PowerShell einfügt.

Was Sie brauchen, bevor Sie anfangen

• Visual FoxPro 9 SP2, installiert. FoxServer kompiliert Ihr Projekt damit.
• FoxServer, installiert. Die 30-Tage-Testlizenz, die bei der Registrierung im Portal ausgestellt wird, reicht für alles hier. Das Setup hat am Ende nach der Lizenzdatei gefragt: Wenn Sie das übersprungen haben, führen Sie es noch einmal aus.
• Einen Browser, welchen auch immer Sie verwenden: Edge, Chrome oder Firefox.
• Die Berechtigung, Programme als Administrator auszuführen auf Ihrem Rechner. Das braucht es nur zum Kompilieren, und in Schritt 1 erkläre ich, warum.

Mehr nicht. Sie müssen keine Konsole öffnen und nichts zusätzlich installieren.

Drei Dinge, die man verstehen muss, bevor man eine Zeile schreibt

Wenn Sie aus diesem Artikel nur einen Kasten lesen, dann diesen.

1. Ihr Code bleibt Ihrer. Er wird nur veröffentlicht. FoxServer übersetzt nichts und zwingt Ihnen kein Framework auf. Eine PROCEDURE einer VFP-Klasse wird zum Endpunkt (einer Webadresse, die antwortet, wie http://127.0.0.1:8099/hola), indem man ihr eine HELP-Klausel hinzufügt:

PROCEDURE pHola(req, res) HELP "GET: hola public"
    LOCAL loRes
    loRes         = THIS.newObject("mensaje")
    loRes.mensaje = "hola"
    RETURN THIS.Ok(loRes)
ENDPROC

Das ist eine API. Der Rest des Artikels ist Detail.

2. Die Route existiert erst, wenn Sie kompilieren. Die Route entsteht in dieser HELP-Klausel und erreicht den Server erst, wenn das Projekt kompiliert wird. Das ist Ursache Nummer eins für „ich habe den Endpunkt hinzugefügt und bekomme ein 404“. Wenn Sie eine Route hinzufügen und sie nicht auftaucht: Es fehlt das Kompilieren.

3. Der Aufruf ist synchron. Ein Endpunkt, der zwei Sekunden braucht, braucht zwei Sekunden und belegt so lange seinen Platz. Für Abfragen ist das bequem; bei einem Vierzig-Sekunden-Prozess gibt man eine Kennung zurück und erledigt die Arbeit an anderer Stelle.

Schritt 1. Visual FoxPro als Administrator öffnen und FoxForge laden

FoxForge ist die Werkstatt, die FoxServer für die Visual-FoxPro-IDE installiert: ein zusätzliches Menü in der Menüleiste, neben File, Edit und Co., aus dem heraus man die Projekte anlegt. Es wird wie jede .app geladen, mit einem DO.

1. Suchen Sie das Symbol von Visual FoxPro 9, das Sie immer verwenden: auf dem Desktop, in der Taskleiste oder im Startmenü.
2. Klicken Sie mit der rechten Maustaste darauf und wählen Sie Als Administrator ausführen. Wo die Option steht, hängt davon ab, wo das Symbol liegt:
   • Auf dem Desktop erscheint sie direkt im Kontextmenü.
   • In der Taskleiste zeigt der erste Rechtsklick nur vfp9.exe: Klicken Sie noch einmal mit der rechten Maustaste auf vfp9.exe, dort steht sie, wie im Bild.
   • Im Startmenü von Windows 11 steht sie unter Mehr.

Je nachdem, wie Ihr Windows eingerichtet ist, fragt es vor dem Öffnen womöglich, ob Sie zulassen wollen, dass die App Änderungen an Ihrem Gerät vornimmt. Das ist die Benutzerkontensteuerung: Wenn sie erscheint, antworten Sie mit Ja. Wenn nichts erscheint und die IDE sich direkt öffnet, ist das auch in Ordnung: Ihr Windows ist so eingestellt, dass es nicht fragt.

Warum als Administrator? Ihr Projekt wird als Multithread-COM-DLL kompiliert, dieselbe, die Sie mit BUILD MTDLL erzeugen würden. Nach dem Kompilieren registriert Visual FoxPro sie in Windows, und das darf nur ein Administrator. Ohne Rechte sieht es so aus, als ende das Kompilieren, aber es bleibt eine halbfertige DLL zurück, die der Server nicht verwenden kann. Nichts anderes braucht Administratorrechte: nur das Kompilieren.

3. Gehen Sie bei geöffnetem Visual FoxPro in das Befehlsfenster. Wenn es nicht zu sehen ist: Menü Window › Command Window oder Strg+F2.
4. Schreiben Sie diese zwei Zeilen und drücken Sie nach jeder die Eingabetaste:

CD "C:\Program Files (x86)\FoxServer\ide"
DO FoxForge.app

Die Anführungszeichen beim CD sind nötig, weil der Pfad Leerzeichen enthält. Wenn Sie FoxServer in einen anderen Ordner installiert haben, ersetzen Sie den Pfad durch Ihren: Es ist der Ordner ide\ der Installation.

Nach einer Sekunde erscheint am Ende der Menüleiste ein neues Menü: FoxForge.

Wenn Sie lieber nichts schreiben möchten: Das FoxServer-Setup legt im Startmenü, im Ordner FoxServer, eine Verknüpfung namens Crear un proyecto (FoxForge) an (der Name ist auch in deutschem Windows spanisch), die Visual FoxPro mit dem Menü bereits geladen öffnet. Öffnen Sie auch diese mit Rechtsklick › Als Administrator ausführen.

Seit 0.9.30 lädt das Öffnen eines FoxServer-Projekts FoxForge von selbst, wenn FoxServer auf dem Rechner installiert ist und das Projekt mit dieser Version erstellt oder aktualisiert wurde. Um es schon vor dem Öffnen eines Projekts zu haben, verwenden Sie diese zwei Zeilen; wenn Sie es immer haben möchten, tragen Sie sie in Ihr Visual-FoxPro-Startprogramm ein. Es funktioniert genauso in Visual FoxPro 9 und in VFP Advanced (VFPA).

Schritt 2. FoxForge auf Englisch

FoxForge spricht Englisch und Spanisch, eine deutsche Oberfläche gibt es nicht. Wählen Sie Englisch: Unter FoxForge › Language muss English markiert sein, wie im Screenshot (wenn die Menüs auf Spanisch erscheinen: FoxForge › Idioma › Inglés). FoxForge merkt sich Ihre Wahl für die nächsten Male.

Ab hier nenne ich die FoxForge-Menüs auf Englisch. Die von Visual FoxPro ebenfalls, denn so erscheinen sie.

Schritt 3. Der Ordner für Ihre Projekte

Wir legen das Projekt in C:\proyectos ab (spanisch für „Projekte“; ich behalte den Namen, weil die Screenshots ihn so zeigen). Der Assistent im nächsten Schritt verlangt, dass der Ordner bereits existiert, also legen wir ihn jetzt an.

Öffnen Sie das Befehlsfenster von Visual FoxPro, wenn es nicht zu sehen ist: Menü Window › Command Window oder Strg+F2. Schreiben Sie diese Zeile und drücken Sie die Eingabetaste:

MD C:\proyectos

Wenn die Antwort lautet, dass der Ordner schon existiert, macht das nichts: Machen Sie weiter.

Ein anderer Ordner? Das Projekt kann liegen, wo Sie wollen, auch in Ihren Dokumenten. Hier verwenden wir C:\proyectos, weil der Pfad kurz ist und sich die Pfade in den folgenden Schritten so besser lesen.

Schritt 4. Das Projekt anlegen

1. Öffnen Sie das Menü FoxForge › New project › Web service / REST API (FoxServer).

2. Es öffnet sich das Fenster New FoxServer project. Füllen Sie es so aus:

Die Namen bleiben in diesem Tutorial spanisch, weil die Screenshots sie so zeigen: Das Projekt heißt Almacen („Lager“).

Der Port ist die „Schalternummer“, an der Ihre API bedient: 8099 ist fast nie belegt.

Während Sie ausfüllen, zeigt der Kasten unten, was passieren wird. Dort muss Folgendes stehen:

Will be created in: C:\proyectos\Almacen\
Will answer at : http://127.0.0.1:8099/

127.0.0.1 ist Ihr eigener Rechner (localhost): Während der Entwicklung antwortet die API nur auf Ihrem Rechner.

Wenn die Schaltfläche Create grau bleibt, lesen Sie den Kasten: Er sagt, was fehlt. Meldet er, dass der Ordner nicht existiert, haben Sie Schritt 3 übersprungen.

3. Klicken Sie auf Create.

Visual FoxPro arbeitet ein paar Sekunden und öffnet Ihnen den Project Manager des Projekts Almacen, wie bei jedem anderen Projekt von Ihnen.

Das hat er in C:\proyectos\Almacen\ angelegt. Es ist die Ausgabe von tree /f, einem Windows-Befehl, der einen Ordner mit seinem gesamten Inhalt zeichnet; Sie können es selbst in einem Fenster der Eingabeaufforderung ansehen:

In src\controllers\ liegt ein DemoController.prg mit sieben Beispiel-Endpunkten (hello, users, search…). FoxForge legt ihn an, damit das Projekt vom ersten Moment an etwas ausliefert. Er gehört nicht zu Ihrem Code: Wenn Sie mit diesem Tutorial fertig sind, entfernen Sie ihn aus dem Projekt und kompilieren neu, dann verschwinden seine Routen.

Schritt 5. Der Controller für die Artikel

Ein Controller ist eine VFP-Klasse mit Endpunkten darin. Wir legen einen für die Artikel des Lagers an. Auch hier bleiben die Namen spanisch, wie in den Screenshots: der Controller Articulos und die Tabelle articulos („Artikel“), die Felder codigo („Code“) und descripcion („Bezeichnung“) und die Routen /articulos.

1. Öffnen Sie im Project Manager den Reiter Code, wählen Sie Programs und klicken Sie auf New….
2. Es öffnet sich ein leerer Programmeditor. Fügen Sie diesen Code vollständig ein:

*-- Articulos.prg: der Controller des Tutorials.
*-- Jede PROCEDURE mit ihrer HELP-Klausel ist ein Endpunkt.
DEFINE CLASS Articulos AS ApiController OLEPUBLIC

    *-- Läuft VOR jeder Anfrage: öffnet die Tabelle.
    FUNCTION BeforeEndpoint(req, res)
        SET DELETED ON
        SET EXCLUSIVE OFF
        USE articulos IN 0 SHARED AGAIN
    ENDFUNC

    *-- Läuft NACH jeder Anfrage: schließt alles.
    PROCEDURE AfterEndpoint(req, res)
        CLOSE DATABASES ALL
    ENDPROC

    *-- GET /articulos: die ganze Tabelle als JSON.
    PROCEDURE pArticulos(req, res) HELP "GET: articulos public as articulos.lista"
        LOCAL lcJson

        SELECT codigo, descripcion, precio, stock ;
            FROM articulos ;
            WHERE activo ;
            ORDER BY descripcion ;
            INTO CURSOR art

        lcJson = THIS.TableToJson("art")
        USE IN SELECT("art")

        RETURN THIS.OkRaw(lcJson)
    ENDPROC

    *-- GET /articulos/A001: ein Artikel nach seinem Code.
    PROCEDURE pArticulo(req, res) HELP "GET: articulos/{codigo} public as articulos.uno"
        LOCAL lcCodigo, loArt

        lcCodigo = req.GetParam("codigo", "")
        IF EMPTY(lcCodigo)
            RETURN THIS.BadRequest("Falta el código del artículo")
        ENDIF

        SELECT articulos
        LOCATE FOR ALLTRIM(articulos.codigo) == ALLTRIM(lcCodigo)
        IF !FOUND()
            RETURN THIS.NotFound("No existe el artículo " + lcCodigo)
        ENDIF

        loArt = THIS.NewObject("codigo,descripcion,precio,stock")
        loArt.codigo      = ALLTRIM(articulos.codigo)
        loArt.descripcion = ALLTRIM(articulos.descripcion)
        loArt.precio      = articulos.precio
        loArt.stock       = articulos.stock

        RETURN THIS.Ok(loArt)
    ENDPROC

    *-- POST /articulos: einen Artikel anlegen.
    PROCEDURE pAlta(req, res) HELP "POST: articulos public as articulos.alta"
        LOCAL loDatos, loNuevo, lcDesc

        loDatos = req.json
        IF ISNULL(loDatos) OR VARTYPE(loDatos) != "O"
            RETURN THIS.BadRequest("El cuerpo tiene que ser un objeto JSON", "cuerpo_invalido")
        ENDIF

        lcDesc = ""
        TRY
            lcDesc = ALLTRIM(TRANSFORM(loDatos.descripcion))
        CATCH
            lcDesc = ""
        ENDTRY

        IF EMPTY(lcDesc)
            RETURN THIS.BadRequest("Falta la descripción", "falta_descripcion")
        ENDIF

        loNuevo = THIS.NewObject("codigo,descripcion")
        loNuevo.codigo      = THIS.NewGuid()
        loNuevo.descripcion = lcDesc

        INSERT INTO articulos (codigo, descripcion, activo) ;
            VALUES (loNuevo.codigo, loNuevo.descripcion, .T.)

        RETURN THIS.Created(loNuevo)
    ENDPROC

ENDDEFINE

Die Meldungen in den Zeichenketten bleiben spanisch, weil sie genau so in den Screenshots der Antworten erscheinen.

3. Speichern Sie mit File › Save (oder Strg+S). Er fragt Sie, wohin, und Vorsicht: Der Dialog öffnet sich nicht im Projektordner, sondern im letzten Ordner, in dem Visual FoxPro war: dem Ordner ide\ von FoxServer, wenn Sie das CD aus Schritt 1 gemacht haben. Am schnellsten kommen Sie so hin: Schreiben Sie C:\proyectos\Almacen\src\controllers in das Feld für den Dateinamen und drücken Sie die Eingabetaste, das bringt Sie in diesen Ordner. Schreiben Sie dann Articulos.prg und klicken Sie auf Speichern.

4. Schließen Sie den Editor. Im Project Manager muss unter Code › Programs jetzt articulos erscheinen.

Wenn er nicht in der Liste erscheint, wurde die Datei gespeichert, aber nicht ins Projekt aufgenommen, und für den Server existiert sie nicht. Wählen Sie Programs, klicken Sie auf Add… und wählen Sie src\controllers\Articulos.prg.

Was jeder Teil tut

Lesen Sie ihn in Ruhe, es ist altbekanntes VFP:

• DEFINE CLASS Articulos AS ApiController OLEPUBLIC. Ihre Klasse erbt von ApiController, und dort lebt alles mit THIS., was Sie darin verwenden. OLEPUBLIC ist das altbekannte Schlüsselwort, damit eine Klasse von außerhalb von VFP verwendet werden kann.
• Die HELP-Klausel liest sich so: "<VERB>: <route> [public] [as <name>]".
  • Das Verb ist die HTTP-Methode: GET zum Abfragen und POST zum Anlegen.
  • Die Route ist das, was in der Adresse hinter dem Port steht. {codigo} ist ein variables Stück: In articulos/A001 hat codigo den Wert A001.
  • public bedeutet, dass für den Aufruf kein Token nötig ist. Ohne, und wenn Sie die Authentifizierung aktivieren, wird eines verlangt.
  • as articulos.lista ist der Name des Endpunkts. Geben Sie ihn immer an: Sonst erfindet FoxServer einen aus der Route, und zwei GET-Endpunkte auf articulos bekommen am Ende denselben Namen und eine [ERROR]-Zeile im Serverfenster.
  • Die HELP-Klausel darf 255 Zeichen nicht überschreiten. Bei 256 kompiliert VFP nicht, und die Fehlermeldung erwähnt die Länge mit keinem Wort.
• BeforeEndpoint und AfterEndpoint laufen vor und nach jeder Anfrage. Hat Ihre Anwendung eine Startroutine, die SETs und Pfade einstellt, gehört sie hierher.
• TableToJson("art") verwandelt einen ganzen Cursor mit einem einzigen Aufruf in JSON. Das ist die Funktion, die neunzig Prozent der Arbeit einer Abfrage-API erspart.
• OkRaw und nicht Ok in pArticulos, weil TableToJson() bereits JSON liefert: Geben Sie es an Ok(), wird es ein zweites Mal umgewandelt und kommt als Text voller Backslashes an. Und umgekehrt: Ok() mit einer Zeichenkette wandelt nichts um und liefert {}. Übergeben Sie immer ein Objekt.
• Achten Sie auf den Alias in pArticulo: Gesucht wird in articulos, der Tabelle, die BeforeEndpoint öffnet, und nicht im Cursor art. Dieser Cursor entsteht und stirbt innerhalb von pArticulos. Ihn hier zu verwenden, liefert den Fehler „No se encuentra el alias ‘ART’“ (Alias nicht gefunden; die Meldung stammt von VFP selbst, und meines spricht Spanisch), einer dieser Fehler, die eine Weile kosten, weil der Code sich einwandfrei liest.
• req ist die eingehende Anfrage: req.GetParam("codigo", "") für die Stücke der Route, req.GetQuery("q", "") für das, was hinter dem ? steht, req.json für den bereits in ein Objekt umgewandelten Body. Das zweite Argument ist der Standardwert; ohne ihn merken Sie spät, dass der Wert fehlte.
• Validieren Sie immer, was hereinkommt: Was über das Netz ankommt, hat nicht Ihr Formular geschrieben. Und verwenden Sie PEMSTATUS() nicht auf req.json, um zu prüfen, ob ein Feld vorhanden ist, denn auf dem Prüfstand scheitert es. Der direkte Zugriff in einem TRY, wie in pAlta, funktioniert immer.
• Was Sie zurückgeben, sind HTTP-Statuscodes, und jeder hat seine Funktion: Ok (200), OkRaw (200), Created (201), NoContent (204), BadRequest (400), Unauthorized (401), Forbidden (403), NotFound (404) und Fail(status, meldung, code) für alles andere. Die vollständige Liste steht in der Referenz.

Schritt 6. Die Beispieltabelle

Wir legen die Tabelle articulos mit zwei Datensätzen zum Ausprobieren an. Wenn Sie schon Ihre eigene haben, steht im Kasten unten, wo sie liegen muss.

Schreiben Sie diese Zeilen ins Befehlsfenster, eine nach der anderen, und drücken Sie nach jeder die Eingabetaste:

CD C:\proyectos\Almacen\build
CREATE DATABASE almacendata
CREATE TABLE articulos (codigo C(32), descripcion C(60), precio N(10,2), stock N(10,0), activo L)
INSERT INTO articulos VALUES ("A001", "Tornillo M6", 0.42, 1200, .T.)
INSERT INTO articulos VALUES ("A002", "Arandela M6", 0.11, 3400, .T.)
CLOSE DATABASES ALL

Drei Details dieser Zeilen, und keines ist eine Laune:

• Die Tabelle liegt in build\. Der Server sucht ein USE articulos ohne Pfad im Ordner der DLL. Wenn Ihre Tabelle schon an anderer Stelle existiert, öffnen Sie sie in BeforeEndpoint mit vollem Pfad oder setzen Sie dort ein SET PATH.
• Sie liegt in einer Datenbank. descripcion hat elf Buchstaben, und eine freie Tabelle akzeptiert keine Feldnamen mit mehr als zehn. Sie würde mit Fehler 1712 antworten, der von doppelten Namen spricht und die Länge mit keinem Wort erwähnt. Und codigo ist C(32), weil der Code, den NewGuid() beim Anlegen erzeugt, so lang ist.
• CLOSE DATABASES ALL am Ende ist Pflicht. Die IDE öffnet Tabellen exklusiv (SET EXCLUSIVE ON ist die Voreinstellung), und solange Sie die Tabelle hier geöffnet haben, kann der Server sie nicht verwenden. Ohne diese Zeile sehen Sie in Schritt 9 einen Fehler 1705. Ich zeige ihn dort, damit Sie ihn wiedererkennen.

Schritt 7. Kompilieren

Kompiliert wird wie immer: mit der Schaltfläche Build… des Project Managers. Es gibt ein einziges Detail, das anders ist als bei Ihren üblichen Projekten, und das ist der Ordner, in dem die DLL gespeichert wird. Lesen Sie es, bevor Sie irgendetwas anklicken.

1. Klicken Sie im Project Manager von Almacen auf Build….
2. Aktivieren Sie in Build Options die Optionen Multi-threaded COM server (dll) und Recompile All Files und klicken Sie auf OK.

3. Visual FoxPro fragt, wo die DLL gespeichert werden soll, und schlägt almacen.dll im Projektordner vor. Nehmen Sie diesen Ordner nicht. Doppelklicken Sie auf den Ordner build, um hineinzugehen, lassen Sie den Namen almacen.dll stehen und klicken Sie auf Speichern.

4. Wenn Sie schon einmal kompiliert haben, fragt Windows, ob Sie almacen.DLL ersetzen wollen. Antworten Sie mit Ja.

Das dauert ein paar Sekunden. Während des Kompilierens liest FoxForge alle HELP-Klauseln und trägt Ihre Routen in die Serverkonfiguration ein: In diesem Moment beginnen Ihre Endpunkte zu existieren. Wenn kein Fehlerfenster erscheint, ist alles kompiliert.

Wenn ein Fehlerfenster erscheint, ist es ein VFP-Fehler in Ihrem Code, mit Datei und Zeile, wie bei jedem Projekt. Korrigieren Sie ihn und kompilieren Sie noch einmal. Am häufigsten beim Einfügen: ein verlorenes Anführungszeichen in einer HELP-Klausel.

Wenn nach dem Kompilieren dieses Fenster erscheint, haben Sie Visual FoxPro ohne Administratorrechte geöffnet:

Wenn Sie diese Optionen unter Current project nicht sehen, haben Sie das Projekt nach dem Laden von FoxForge geöffnet: Klicken Sie auf FoxForge › Refresh menu.

Schritt 8. Den Server starten

Der Server ist ein eigenes Programm, FoxServer.Host.exe, das Ihre DLL lädt und die Anfragen bedient. Starten Sie ihn aus dem Menü: FoxForge › Current project › Start the server (dasselbe Bild wie in Schritt 7). FoxForge weiß, wo FoxServer installiert ist und wo die Konfiguration Ihres Projekts liegt.

Lieber das Befehlsfenster? Diese Zeile tut dasselbe. RUN /N öffnet ein Programm, ohne auf sein Ende zu warten, und --config sagt dem Server, in welchem Ordner die Konfiguration Ihres Projekts liegt. Wenn Sie FoxServer in einen anderen Ordner installiert haben, ersetzen Sie den ersten Pfad durch den Ordner bin\ Ihrer Installation.

RUN /N "C:\Program Files (x86)\FoxServer\bin\FoxServer.Host.exe" --config C:\proyectos\Almacen\build

Es öffnet sich ein schwarzes Fenster: Das ist der Server. Nach ein paar Sekunden muss es mit diesen Zeilen enden:

Listening: http://127.0.0.1:8099/
  Server : Almacen [api] - C:\proyectos\Almacen\build\almacen.DLL

Press Ctrl+C to stop.

Etwas weiter oben sehen Sie Ihre beiden geladenen Controller: DemoController mit 7 endpoint(s) loaded und Articulos mit 3 endpoint(s) loaded.

Lassen Sie dieses Fenster offen, solange Sie testen: Wenn Sie es schließen, geht die API aus. Jede eingehende Anfrage hinterlässt dort ein paar Zeilen, und dort schauen Sie nach, wenn etwas nicht funktioniert. Um den Server anzuhalten, drücken Sie darin Strg+C oder schließen es.

Schritt 9. Im Browser testen

Öffnen Sie Ihren Browser und schreiben Sie diese Adresse in die Adressleiste, als wäre es eine Webseite:

http://127.0.0.1:8099/articulos

Sie müssen Ihre Tabelle als JSON sehen, nach Bezeichnung sortiert, „Arandela“ (Unterlegscheibe) vor „Tornillo“ (Schraube), wie es die Abfrage verlangt:

[{
  "codigo": "A002",
  "descripcion": "Arandela M6",
  "precio": 0.11,
  "stock": 3400
},{
  "codigo": "A001",
  "descripcion": "Tornillo M6",
  "precio": 0.42,
  "stock": 1200
}]

Jetzt ein einzelner, nach seinem Code:

http://127.0.0.1:8099/articulos/A001

{
  "codigo": "A001",
  "descripcion": "Tornillo M6",
  "precio": 0.42,
  "stock": 1200
}

Und einer, den es nicht gibt, um das NotFound aus dem Code zu sehen:

http://127.0.0.1:8099/articulos/ZZZZ

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No existe el artículo ZZZZ",
  "instance": "/articulos/ZZZZ",
  "code": "not_found"
}

Dieses Format ist Problem Details, RFC 9457: die Standardform, einen Fehler in einer API zu beschreiben, die die Programme, die sie aufrufen werden, bereits verstehen. Das detail ist Ihre Meldung, genau so, wie Sie sie in THIS.NotFound(...) geschrieben haben. Erfolgreiche Antworten tragen diesen Umschlag nicht: Sie kommen so heraus, wie Sie sie oben gesehen haben.

Wenn Sie stattdessen ein 500 mit „1705“ sehen

Der Wortlaut stammt von VFP selbst und erscheint daher in der Sprache Ihres VFP; meines spricht Spanisch:

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal server error: Error: .beforeendpoint c:\\proyectos\\almacen\\build\\src\\controllers\\articulos.prg Error en la línea 9 Denegado c:\\proyectos\\almacen\\build\\articulos.dbf al acceso al archivo. 1705, Error Code: 1705",
  "instance": "/articulos"
}

Das ist die Tabelle, die in Ihrem Visual FoxPro noch geöffnet ist: Sie haben das CLOSE DATABASES ALL aus Schritt 6 übersprungen. Schreiben Sie es jetzt ins Befehlsfenster und laden Sie die Seite neu, ohne den Server anzufassen.

Schritt 10. Einen Artikel aus Visual FoxPro anlegen

Ein Browser kann nur mit GET anfragen. Zum Anlegen braucht es ein POST mit dem Artikel darin, und das machen wir direkt aus Visual FoxPro mit dem Windows-Objekt ServerXMLHTTP, demselben, mit dem viele von Ihnen bereits Webdienste aufrufen. Schreiben Sie diese Zeilen ins Befehlsfenster, eine nach der anderen:

oHttp = CREATEOBJECT("MSXML2.ServerXMLHTTP.6.0")
oHttp.Open("POST", "http://127.0.0.1:8099/articulos", .F.)
oHttp.SetRequestHeader("Content-Type", "application/json")
oHttp.Send('{"descripcion":"Arandela M8"}')
? oHttp.Status
? oHttp.ResponseText

Im Hauptfenster von Visual FoxPro müssen ein 201 erscheinen, also „angelegt“, und der neue Artikel mit seinem Code:

201
{
  "codigo": "4241c943794c45ccac61dd4af6361c44",
  "descripcion": "Arandela M8"
}

Ihr Code wird ein anderer sein: Es ist eine eindeutige Kennung, die bei jedem Anlegen neu erzeugt wird. Gehen Sie zurück in den Browser, laden Sie http://127.0.0.1:8099/articulos neu, und da ist er, mit Preis und Bestand auf null, weil wir nur die Bezeichnung geschickt haben.

Schritt 11. Etwas ändern und neu kompilieren

So wird Ihr Alltag aussehen: Sie ändern den Code, kompilieren und testen. Es gibt ein Detail, das man von Anfang an kennen sollte.

Beim Kompilieren hält der Server an. Die DLL ist in Gebrauch, solange der Server sie geladen hat, und Windows lässt nicht zu, dass sie überschrieben wird. FoxForge hält ihn vor dem Kompilieren für Sie an, und das schwarze Fenster schließt sich von selbst.

Der Zyklus ist also:

1. Ändern Sie in Articulos.prg, was Sie wollen, und speichern Sie.
2. Drücken Sie Strg+F7 (oder FoxForge › Current project › Build the DLL into build\). Es kompiliert und startet den Server von selbst neu.
3. Laden Sie den Browser neu.

Wenn Sie mit der Schaltfläche Build… kompilieren, kommt der Server nicht von selbst zurück: Gehen Sie beim Speichern in den Ordner build, antworten Sie beim Ersetzen mit Ja und starten Sie ihn erneut mit FoxForge › Current project › Start the server oder mit der Zeile RUN /N aus Schritt 8 (gehen Sie im Befehlsfenster mit der Pfeiltaste bis zu ihr hoch und drücken Sie die Eingabetaste).

Wenn Sie einen Endpunkt hinzufügen und der Browser ein 404 liefert, fehlt dieser Zyklus. Denken Sie an die drei Dinge vom Anfang: Die Route existiert erst, wenn Sie kompilieren.

Wenn etwas nicht klappt

Ein Detail für den Moment, in dem andere Rechner Sie aufrufen sollen. Das Projekt entsteht so, dass es nur auf 127.0.0.1 antwortet, von außen kommt also nicht einmal eine Verbindung zustande: Das ist nicht die Lizenz, das ist die Konfiguration (host in build\Almacen.json). Wenn Sie es auf die IP Ihres Rechners ändern, sehen Sie das Zweite: Bekommen Sie statt 200 ein 403, liegt es nicht an Ihrem Endpunkt, sondern an der Lizenz. Eine Developer-Lizenz nimmt nur Anfragen vom eigenen Rechner an. Um andere zu bedienen, braucht es eine Runtime-Lizenz, die auf dem Server des Kunden installiert wird. In der Entwicklung brauchen Sie sie nicht.

Was Sie getan haben, und was nicht

Sie haben eine Tabelle Ihrer Anwendung als REST-API mit drei Endpunkten veröffentlicht, ohne die IDE zu verlassen, ohne die Logik neu zu schreiben, ohne die Sprache zu wechseln und ohne ein Framework dazwischen. Alles, was Sie geschrieben haben, ist VFP.

Was Sie noch nicht getan haben, ist, sie in Produktion zu bringen: HTTPS-Zertifikat, dass der Server von selbst als Windows-Dienst startet, die Logs und wie man eine neue Version ausrollt, ohne den Server herunterzufahren. Das ist das nächste Tutorial, denn dort bleiben die Leute, die bereits laufende Systeme haben, am häufigsten hängen. Bis dahin erklärt es die FoxServer-Dokumentation Stück für Stück.

Mögen Sie die Kommandozeile? Es gibt dieses Tutorial auch als CLI-Version, mit denselben Schritten als Befehle, die man einfügen und wiederholen kann.

Wenn hier etwas nicht so funktioniert, wie es geschrieben steht, schreiben Sie an soporte@irwinrodriguez.dev, mit dem, was Sie auf dem Bildschirm sehen. Jede Ausgabe in diesem Artikel ist aus einem echten Lauf kopiert, und wenn Ihre anders aussieht, möchte ich es wissen.