Fabric-Apps-Vorlagen erstellen und teilen

Eine Vorlage ist ein Ausgangspunkt, den das Rayfin CLI in eine neue Fabric-App integriert. Wenn du npx rayfin init oder npm create @microsoft/rayfin@latest ausführst, kopiert die CLI die Dateien der Vorlage in dein Projekt und wendet einige Gerüsttransformationen an. Indem Sie Ihre eigene Vorlage erstellen, können Sie einen bevorzugten Stack, ein Datenmodell oder eine Reihe von Konventionen einmal erfassen und im gesamten Team wiederverwenden.

Dieser Artikel zeigt Ihnen, wie das geht:

  • Erstellen Sie eine einzige Vorlage.
  • Kombinieren Sie mehrere Vorlagen zu einem Katalog.
  • Verteilt Vorlagen über ein Git-Repository oder eine Vorlagenregistry.

Voraussetzungen

So funktionieren Vorlagen

Benutzerdefinierte Vorlagen in einem lokalen Verzeichnis oder Git-Repository verwenden ein rayfin-template.yml Manifest. Eingebaute Vorlagen, die mit der CLI ausgeliefert werden, verwenden Vorlagenmetadaten in package.json. Eine Vorlagen-Registry enthält Namen, die zu in Git gespeicherten Vorlagen aufgelöst werden.

Wenn die CLI eine Vorlage unterstützt, kopiert sie die Vorlagendateien in das Zielverzeichnis und wendet dann eine kleine, feste Menge von Transformationen an:

  • Schreibt das name Feld package.json in den Slug des neuen Projekts um. Wenn package.json JSON nicht gültig ist, lässt die CLI es unverändert.
  • Ersetzt die Platzhalter {{PROJECT_NAME}}, {{PROJECT_NAME_PASCAL}} und README.md in {{PROJECT_NAME_KEBAB}}.
  • Ersetzt den Platzhalter __projectName__ in Dateinamen durch den Projektnamen.
  • Überspringt rayfin-template.yml, .git, node_modules, .DS_Store, und Thumbs.db, und folgt nicht auf Symlinks.

Alle anderen Dateiinhalte werden unverändert kopiert. Nach dem Gerüst folgt die CLI:

  • Installiert Projektabhängigkeiten, einschließlich Abhängigkeiten unter rayfin/functions/ , wenn dieses Verzeichnis vorhanden ist.
  • Synchronisiert die generierte Rayfin-Konfiguration, einschließlich rayfin.yml und zugehöriger Scaffold-Dateien.
  • Installiert verwaltete Agentdateien, einschließlich des Schlüssels mcpServers.rayfin in .mcp.json und des Verzeichnisses .agents/skills/rayfin/.
  • Datensätze verwaltete Dateien in rayfin/.lockfile.json.

Wenn deine Vorlage eine AGENTS.md Datei bereitstellt, bewahrt die CLI sie und überschreibt sie nicht. Füge keinen mcpServers.rayfin Eintrag in die .mcp.json Datei der Vorlage ein, da die CLI diesen Eintrag besitzt und verwaltet.

Der Projektname stammt von dem Verzeichnisargument, das du beim Scaffold übergibst. Zum Beispiel erzeugt npm create @microsoft/rayfin@latest my-app ein Projekt namens my-app. Um einen anderen Namen zu verwenden, übergeben Sie --project-name.

Vorlage erstellen

Eine Vorlage ist ein Verzeichnis, das ein rayfin-template.yml-Manifest und die Dateien enthält, die als Gerüst erstellt werden sollen.

Schritt 1: Beginnen Sie mit einer funktionierenden App

Beginnen Sie mit einer Fabric-App, die korrekt ausgeführt und bereitgestellt wird. Entferne alles, was speziell für deinen Arbeitsplatz oder deine Umgebung ist, damit die Verbraucher in einem sauberen Zustand starten. Die CLI kann Werte wie die Workspace-ID und API-URL ausfüllen, wenn der Consumer das Projekt initialisiert oder bereitstellt, daher sollten Sie sie nicht fest programmieren.

Schritt 2: Fügen Sie ein Manifest hinzu

Füge eine rayfin-template.yml Datei hinzu, die auf die Vorlagendateien verweist. Für eine einzelne Vorlage, deren Dateien im selben Verzeichnis wie das Manifest liegen, verwenden Sie einen Eintrag mit path: .:

apiVersion: v1
metadata:
  name: my-starter
  displayName: My Starter
  description: A starter template for Fabric Apps
entries:
  - name: my-starter
    path: .

Ein Manifest mit nur einem Eintrag wird automatisch gerüstet, ohne dass der Benutzer eine Vorlage auswählen muss.

Schritt 3: Platzhalter hinzufügen

Verwenden Sie Platzhalter, sodass jedes aus einem Gerüst erzeugte Projekt einen eigenen Namen erhält:

  • In README.md verwenden Sie {{PROJECT_NAME}}, {{PROJECT_NAME_KEBAB}} oder {{PROJECT_NAME_PASCAL}}.
  • Verwenden Sie in einem Dateinamen __projectName__. Zum Beispiel wird src/__projectName__.config.ts zu src/my-app.config.ts, wenn ein Konsument in my-app scaffolded wird.

Schritt 4: Teste die Vorlage lokal

Erstellen Sie das Grundgerüst im lokalen Verzeichnis, um die Ausgabe zu prüfen, bevor Sie veröffentlichen:

npx rayfin init test-output -t ./my-template --yes

Überprüfen Sie das Verzeichnis test-output und vergewissern Sie sich, dass das generierte Projekt kompiliert und ausgeführt werden kann.

Tip

Ein nackter Wert, der an -t übergeben wird, wird als Vorlagenname aufgelöst, nicht als Pfad. Verwenden Sie ./, ../ oder einen absoluten Pfad, wenn Sie auf ein lokales Verzeichnis verweisen.

Erstellen Sie einen Katalog von Vorlagen

Um mehr als eine Vorlage aus einer einzigen Quelle zu veröffentlichen, erstellen Sie ein Root-Katalog-Manifest und listen Sie jede Vorlage in ihrem Array entries auf. Jeder Eintrag muss auf ein Verzeichnis verweisen, das ein eigenes rayfin-template.yml Manifest enthält.

Verwenden Sie zum Beispiel folgende Struktur:

my-collection/
|-- rayfin-template.yml
`-- templates/
    |-- api-service/
    |   |-- rayfin-template.yml
    |   `-- package.json
    `-- fullstack/
        |-- rayfin-template.yml
        `-- package.json

Im Stammverzeichnis rayfin-template.yml, weisen Sie jeden Eintrag seinem Vorlagenverzeichnis zu:

apiVersion: v1
metadata:
  name: my-collection
  displayName: My Collection
  description: A collection of Fabric Apps templates
entries:
  - name: api-service
    path: ./templates/api-service
    description: REST API with a Rayfin data layer
  - name: fullstack
    path: ./templates/fullstack
    description: Full-stack app with authentication and data

In jedem Vorlagenverzeichnis wird ein Einzeleintrags-Manifest hinzugefügt, das auf die Dateien in diesem Verzeichnis verweist. Zum Beispiel enthält templates/api-service/rayfin-template.yml:

apiVersion: v1
metadata:
  name: api-service
  displayName: API Service
entries:
  - name: api-service
    path: .

Wenn für einen Consumer das Gerüst aus einer Quelle mit mehreren Einträgen erstellt wird, zeigt die CLI eine interaktive Auswahl an. Für nicht-interaktive Abläufe übergibt der Konsument --template-name mit dem name oder path des Eintrags:

npx rayfin init my-app -t https://github.com/example-org/templates.git --template-name api-service --yes

Gruppenvorlagen für verschachtelte Navigation

Für größere Sammlungen verwenden Sie groupEinträge, um Vorlagen hierarchisch zu organisieren. Sowohl lokale als auch Git-unterstützte Vorlagenquellen unterstützen gruppierte Navigation. Der Auswahlassistent führt die Nutzer durch jede Stufe.

entries:
  - group:
      name: starters
      displayName: Starter apps
      entries:
        - name: hello-world
          path: ./starters/hello-world
        - name: todo-app
          path: ./starters/todo-app
  - name: standalone-app
    path: ./standalone-app

Note

Die Awesome Rayfin Galerie ist ein öffentlicher, flacher Katalog von Fabric Apps Vorlagen. Nutzen Sie es als Arbeitsbeispiel für einen Katalog oder als Gerüst daraus und wählen Sie interaktiv eine Vorlage aus:

npm create @microsoft/rayfin@latest my-app -- --template https://github.com/microsoft/awesome-rayfin

Vorlagen verteilen

Nachdem deine Vorlage lokal funktioniert, teile sie, damit andere daraus aufbauen können.

Teilen Sie ein Git-Repository

Veröffentlichen Sie die Vorlage als Git-Repository und geben Sie den Konsumenten die URL an.

  1. Das Repository initialisieren und pushen.

    git init
git add .
git commit -m "Initial template"
git remote add origin https://github.com/example-org/my-template.git
git push -u origin main

  2. Markiere ein Release, damit Scaffolds erneut erstellt werden können.

    git tag v1.0.0
git push origin v1.0.0

  3. Teile die URL. Consumer heften sich durch Anhängen von #<ref> an das Tag an.

    npx rayfin init my-app -t https://github.com/example-org/my-template.git#v1.0.0

Die CLI unterstützt HTTPS, SSH git@host:org/repo.gitund file:// URLs. Es führt ein flaches Klonen in ein temporäres Verzeichnis durch, erstellt das Projektgrundgerüst und löscht anschließend den Klon. Als Referenz verwenden Sie einen Branchnamen, einen Tagnamen oder den vollständigen 40-stelligen Commit-SHA. Die CLI lehnt abgekürzte SHAs ab.

Bei privaten Repositories verwendet die CLI Ihre bestehenden Git-Zugangsdaten und deaktiviert interaktive Eingabeaufforderungen, sodass fehlende Zugangsdaten sofort zu einem Fehler führen, anstatt hängen zu bleiben. Führe bei GitHub-Repositories gh auth setup-git aus, um Anmeldeinformationen über den Git Credential Manager zu verwalten.

Registrieren Sie eine Vorlage

Registrieren Sie eine Vorlage, damit sie in npx rayfin init --list-templates und in der interaktiven Auswahl erscheint, ohne dass Benutzer sich die URL merken müssen. Füge an einem dieser Orte einen Eintrag zu einer template-registries.yml Datei hinzu:

Dienstebene Pfad Wann verwenden?
Gebündelt Im Lieferumfang der Rayfin CLI enthalten First-Party-Vorlagen, die mit der CLI verwaltet werden. Diese Stufe ist nur für Verbraucher lesegeschützt.
User-global ~/.rayfin/template-registries.yml Vorlagen, die du in vielen Projekten auf diesem Gerät verwendest.
Lokal für das Projekt <projectDir>/.rayfin/template-registries.yml Vorlagen, die an ein bestimmtes Projekt angepinnt sind. Committiere die Datei zusammen mit dem Repository.

Registry-Namen müssen zwischen den Stufen einzigartig sein. Die CLI schützt als default oder firstClass markierte gebündelte Einträge vor Überschreibungen. Es überspringt andere doppelte Namen und meldet eine Warnung in der --list-templates Ausgabe.

Ein Registrierungseintrag benennt das Repository und optional die Referenz, um zu pinnen:

registries:
  - name: my-starter
    displayName: My Starter
    description: Our team's Fabric Apps starter
    url: https://github.com/example-org/my-template.git
    ref: "v1.0.0"

Nachdem Sie die Vorlage registriert haben, stellen die Verbraucher nach Namen auf:

npx rayfin init my-app -t my-starter

Wenn du einen neuen Tag veröffentlichst, aktualisiere das ref und committe die Änderung, damit alle im Team die Änderung übernehmen.

Registereinträge unterstützen folgende Felder:

Feld Erforderlich Description
name Yes Eindeutiger Bezeichner für den Eintrag.
url Yes Git-URL des Vorlagen-Repositorys.
displayName No Lesbares Etikett. Wird standardmäßig auf name festgelegt.
description No Kurze Beschreibung, die in Auswahlelementen und --list-templates angezeigt wird.
ref No Git-Tag, -Branch oder vollständiger Commit-SHA, auf den fixiert werden soll. Verwendet standardmäßig den Standard-Branch. Anführungswerte, die YAML als Zahlen interpretieren könnte, wie zum Beispiel "1.0".
path No Unterverzeichnis im Repository, in dem sich das Manifest befindet.
templateName No Für ein Repository mit mehreren Vorlagen der Eintrag, der vorab ausgewählt werden soll, damit Nutzer den Auswahldialog überspringen.

Wenn Sie eine Vorlage erstellen, die andere nützlich finden könnten, sollten Sie sie in die Awesome Rayfin-Galerie eintragen, die von der Community kuratierte Sammlung von Fabric-Apps-Vorlagen. Für erforderliche Dateien, Metadatenkonventionen und wie man eine Pull Request einreicht, siehe die beitragende Anleitung der Galerie.

Manifestreferenz

Ein Manifest rayfin-template.yml hat folgende Form:

apiVersion: v1            # Required. Must be 'v1'.
metadata:
  name: my-collection     # Required. Identifier for the manifest.
  displayName: My Collection
  description: Optional description.
  version: 1.2.0          # Accepted, currently informational only.
  tags: [todo, auth]      # Accepted, currently informational only.
entries:                  # Required. At least one entry.
  - name: api-service     # Template entry. Scaffolds files from path.
    path: ./api-service
    description: REST API with a Rayfin data layer.

Die Werte metadata.displayName und metadata.description werden angezeigt, wenn ein Benutzer ein Gerüst aus der Vorlage erstellt. Das Schema akzeptiert die Felder metadata.version und metadata.tags, aber die CLI macht sie derzeit nicht sichtbar. Gruppenbeschreibungen erscheinen im Multi-Template-Picker, aber Beschreibungen von Blatteinträgen werden derzeit nicht angezeigt.

Verwandte Inhalte

  • Zuletzt aktualisiert um