Übersicht über Azure Developer CLI-Vorlagen

Eine Azure Developer CLI(azd)-Vorlage ist ein Code-Repository, das den azd Konventionen folgt. Es kombiniert Projektkonfiguration, Infrastruktur als Code und optionale Anwendungsquelle, sodass Sie wiederholbare Azure Umgebungen und Bereitstellungen erstellen können.

Vorlagen können verschiedene Projekttypen unterstützen, darunter:

• Eine vollständige Anwendung mit einem oder mehreren bereitstellungsfähigen Diensten.
• Eine nur Infrastrukturlösung ohne Anwendungscode.
• Ein wiederverwendbarer Ausgangspunkt, den ein anderer Entwickler initialisieren und erweitern kann.
• Ein vorhandenes Projekt, das Sie für die Provisionierung und Bereitstellung mit azd vorbereiten.

In diesem Artikel wird die Struktur einer Vorlage erläutert und beschrieben, wie azd Befehle deren Dateien verwenden.

Gründe für die Verwendung einer Vorlage

Eine Vorlage erfasst die Entscheidungen, die zum Ausführen eines Projekts auf Azure erforderlich sind. Je nach Projekt kann folgendes definiert werden:

• Azure Ressourcen und deren Konfiguration.
• Bereitstellungsfähige Anwendungsdienste und Verpackungsanweisungen.
• Verbindungen zwischen Anwendungsdiensten und Azure Ressourcen.
• Umgebungsspezifische Parameter und Ausgaben.
• Lokale Entwicklung, kontinuierliche Integration und kontinuierliche Bereitstellungskonfiguration.

Da die Konfiguration mit dem Projekt gespeichert ist, können Teams Änderungen in der Quellcodeverwaltung überprüfen und konsistente Entwicklungs-, Test- und Produktionsumgebungen erstellen.

Wie azd eine Vorlage verwendet

Die Dateien in einer Vorlage unterstützen verschiedene Phasen des azd Workflows:

• azd init initialisiert das Projekt und erstellt eine azd Umgebung. Sie kann auch GitHub Copilot verwenden, um eine ursprüngliche Vorlage zu generieren oder eine vorhandene Vorlage zu kopieren.
• azd provisionwertet die Infrastrukturdefinitionen aus und erstellt oder aktualisiert Azure Ressourcen.
• azd package bereitet bereitstellungsfähige Anwendungsdienste gemäß azure.yaml vor.
• azd deployordnet jedem Dienst seinen Azure Host zu und stellt das Anwendungspaket bereit.
• azd up führt die Provisionierungs-, Paketierungs- und Bereitstellungsphasen in einem kombinierten Workflow aus.

Die Vorlagendateien bleiben während dieses Prozesses normale Quelldateien. Sie können sie mit dem Rest des Projekts überprüfen, bearbeiten und versionieren.

Erkunden der Azure Developer CLI-Vorlagenstruktur

azd Vorlagen sind Standardcoderepositorys mit zusätzlichen Konfigurations- und Infrastrukturressourcen. Die meisten Vorlagen verwenden die folgende Struktur:

• azure.yaml file – Definiert das Projekt und ordnet bereitstellungsfähige Quellverzeichnisse Azure Ressourcen zu.
• infra folder – Enthält die Bicep- oder Terraform-Dateien für Infrastructure as Code, mit denen die Azure-Ressourcen erstellt werden.
• src ordner – Enthält häufig bereitgestellten Anwendungsquellcode. Nur Infrastrukturvorlagen können die Anwendungsquelle weglassen, und Anwendungsvorlagen können andere Quellverzeichnisnamen verwenden.
• .azure folder - Enthält lokale Umgebungen und Werte, die von azd erstellt wurden. Dieser Ordner ist der lokale Projektstatus und wird normalerweise nicht als Teil einer wiederverwendbaren Vorlage freigegeben.

Eine allgemeine azd Vorlage kann beispielsweise mit der folgenden Ordnerstruktur übereinstimmen:

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd Vorlagen enthalten optional auch einen oder mehrere der folgenden Ordner:

• .github folder – Enthält CI/CD-Workflowdateien für GitHub Actions.
• .azdo ordner – Wenn Sie Azure Pipelines für CI/CD verwenden möchten, definieren Sie die Workflowkonfigurationsdateien in diesem Ordner.
• .devcontainer folder – Definiert eine Entwicklungscontainerumgebung für das Projekt.

Das folgende Diagramm zeigt, wie die primären Vorlagenressourcen zusammenarbeiten:

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

Erforderliche und optionale Ressourcen

Die genaue Struktur variiert je nach Projekt, aber die meisten Vorlagen verwenden die folgenden Ressourcen.

azure.yaml

Die azure.yaml Datei ist die primäre Projektkonfigurationsdatei. Er definiert den Projektnamen und kann bereitstellungsfähige Dienste, Infrastrukturanbieter, Hooks, Workflows und anderes azd Verhalten definieren.

Bei einem Anwendungsdienst identifiziert azure.yaml in der Regel Folgendes:

• Der Pfad zur Anwendungsquelle.
• Die Programmiersprache oder Verpackungsstrategie.
• Der Azure Dienst, der die Anwendung hosten soll.
• Build-, Bereitstellungs-, Container- oder Kubernetes-Einstellungen.

Nur Infrastrukturvorlagen können Anwendungsdienste weglassen. Das vollständige Konfigurationsmodell finden Sie im azure.yaml Schema.

Im folgenden Beispiel werden zwei Anwendungsdienste definiert. Die Dienstnamen, Quellpfade, Sprachen und Hostingziele geben an azd , was sie packen und wo sie bereitgestellt werden sollen:

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

Infrastruktur als Code

Die meisten Vorlagen enthalten ein infra-Verzeichnis mit Bicep- oder Terraform-Dateien. Diese Dateien definieren die Azure Ressourcen, Rollenzuweisungen, Netzwerk, Anwendungseinstellungen und Bereitstellungsausgaben, die für das Projekt erforderlich sind.

Für den Standard-Bicep-Anbieter verwendet azd normalerweise infra/main.bicep als Einstiegspunkt für die Bereitstellung und infra/main.parameters.json, um azd-Umgebungswerte Bicep-Parametern zuzuordnen. Terraform-Vorlagen verwenden häufig infra/main.tf und zugehörige Terraform-Dateien.

Beispielsweise kann eine Bicep-Parameterdatei die von azd ausgewählten Werte an die Infrastrukturbereitstellung übergeben:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

Nach Abschluss der Bicep-Bereitstellung speichert azd Ausgabewerte des Einstiegspunkts als Umgebungswerte. Anwendungsdienste und Hooks können diese Werte für Ressourcenendpunkte, Namen und andere Laufzeitkonfigurationen verwenden.

output API_ENDPOINT string = api.outputs.uri

Anwendungsquelle

Die Anwendungsquelle ist optional. Wenn eine Vorlage bereitstellbare Dienste enthält, verweist jede Dienstdefinition in azure.yaml auf ihr Quellverzeichnis. Eine Vorlage kann Dienste unter srcorganisieren, Verzeichnisse an anderer Stelle im Repository verwenden oder einen Dienst auf den Repositorystamm verweisen.

Der Ordnername selbst ist nicht relevant. Der Wert project in azure.yaml bestimmt, wo azd jeden Dienst findet.

Umgebungskonfiguration

Das Verzeichnis .azure enthält den Status der lokalen Umgebung und Werte, die von azd erstellt wurden. Er kann Abonnement-, Standort-, Ressourcenname-, Endpunkt- und Bereitstellungsausgabewerte für mehrere Umgebungen enthalten.

Behandeln Sie dieses Verzeichnis als lokalen Zustand und nicht als wiederverwendbare Vorlagenressource. Committen Sie keine Umgebungsdateien, die Geheimnisse oder umgebungsspezifische Werte enthalten.

Zugehörige Ressourcen

Vorlagen können auch Folgendes enthalten:

• GitHub Actions- oder Azure-Pipelines-Definitionen.
• Dockerfiles und Containerkonfiguration.
• Konfiguration des Entwicklungscontainers.
• Befehls- und Diensthaken.
• Tests, Skripts und Projektdokumentation.

Diese Elemente sind optional und sollten nur dann enthalten sein, wenn sie die beabsichtigte Nutzung der Vorlage unterstützen.

Dienst- und Ressourcenzuordnung

Um einen Anwendungsdienst bereitzustellen, azd muss seine Definition in azure.yaml einer bereitgestellten Azure-Ressource zuordnen. Standardmäßig findet azd eine Ressource, deren azd-service-name-Tag dem Dienstnamen entspricht.

Ein Dienst mit dem Namen api ordnet z. B. eine Ressource zu, die mit azd-service-name: apimarkiert ist. Sie können stattdessen die resourceName Diensteigenschaft verwenden, um das Bereitstellungsziel explizit zu identifizieren.

Der folgende Bicep Ausdruck fügt das Discoverytag zu den vorhandenen Tags einer Ressource hinzu:

tags: union(tags, {
  'azd-service-name': 'api'
})

Achten Sie beim Bearbeiten einer Vorlage darauf, dass Dienstnamen, Einstellungen für die Ressourcenermittlung, Infrastruktur-Ausgabewerte und die Umgebungsvariablen der Anwendung aufeinander abgestimmt bleiben.

Erstellen oder Anpassen einer Vorlage

Es wird empfohlen, auszuführen und azd init auszuwählen. Die dedizierte Copilot-Agent Sitzung kann vorhandene Dateien analysieren, ein neues Projekt planen, Vorlagenressourcen generieren und das Ergebnis überprüfen. Informationen zu diesem Workflow und anderen Erstellungsmethoden finden Sie unter "Beginnen mit einer neuen Vorlage".

Die generierten Dateien sind nicht an Copilot gebunden. Sie können die Vorlagendateien direkt nach der Initialisierung durchsuchen und bearbeiten . Sie können dieselben Dateien auch manuell oder mit einem anderen KI-Codierungs-Agent erstellen.

Wenn eine Vorlage aus Microsoft, Ihrer Organisation oder der Entwicklercommunity bereits eine nützliche Architektur bietet, beginnen Sie mit der vorhandenen Vorlage, und passen Sie sie für Ihr Projekt an. Durchsuchen Sie die verfügbaren Vorlagen in den Vorlagenkatalogen.

Richtlinien für die Vorlagenverwendung

Jede Vorlage wird vom Besitzer gemäß der Vereinbarung lizenziert, die die Vorlage begleitet. Ermitteln Sie, welche Lizenz gilt, bevor Sie eine Vorlage verwenden oder verteilen.

Microsoft ist nicht für Nicht-Microsoft-Vorlagen verantwortlich und prüft sie nicht auf Sicherheits-, Datenschutz-, Kompatibilitäts- oder Leistungsprobleme. Vorlagen, einschließlich Microsoft bereitgestellter Vorlagen, werden von einem Microsoft Supportprogramm oder -service nicht unterstützt und werden ohne Garantie bereitgestellt.

Überprüfen Sie alle Vorlagendateien vor der Bereitstellung. Bewerten Sie insbesondere Rollenzuweisungen, Netzwerkexposition, Authentifizierungsmethoden, Dienstebenen, Ressourcenstandorte und erwartete Kosten.

Nächste Schritte

Übersicht über die Vorlagenentwicklung