Partager via

Notions de base d’ASP.NET Core Blazor

  • Article

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 9 de cet article.

Les articles Notions de base fournissent des conseils sur les concepts fondamentaux de Blazor. Certains concepts sont liés à la compréhension de base des composants Razor, qui sont décrits plus loin dans la section suivante de cet article et abordés en détail dans les articles Composants.

Concepts de rendu statiques et interactifs

Les composants Razor sont affichés de manière statique ou interactive.

Le rendu statique ou statique est un scénario côté serveur, ce qui signifie que le composant est rendu sans la capacité d’interaction entre l’utilisateur et le code .NET/C#. Les événements DOM JavaScript et HTML ne sont pas affectés, mais aucun événement utilisateur sur le client ne peut être traité avec .NET s’exécutant sur le serveur.

Le rendu interactif ou interactif signifie que le composant a la capacité de traiter les événements .NET via du code C#. Les événements .NET sont traités sur le serveur par le runtime ASP.NET Core ou dans le navigateur sur le client par le runtime WebAssembly Blazor.

Important

Lors de l’utilisation d’une Blazor Web App, la plupart des composants de l’exemple de documentation Blazornécessitent une interactivité pour fonctionner et démontrer les concepts couverts par les articles. Lorsque vous testez un composant d’exemple fourni par un article, assurez-vous que l’application adopte une interactivité globale ou que le composant adopte un mode de rendu interactif.

Vous trouverez plus d’informations sur ces concepts et sur la façon de contrôler le rendu statique et interactif dans l’article Modes de rendu ASP.NET Core Blazor plus loin dans la documentation Blazor.

Concepts de rendu du client et du serveur

Tout au long de la documentation Blazor, l’activité qui se déroule sur le système de l’utilisateur est dite sur le client ou côté client. L’activité qui se produit sur un serveur est dite sur le serveur ou côté serveur.

Le terme rendu signifie produire le balisage HTML affiché par les navigateurs.

  • Le rendu côté client (CSR) signifie que le balisage HTML final est généré par le runtime .NET WebAssembly sur le client. Aucune interface utilisateur générée par le client de l’application n’est envoyée à partir d’un serveur au client pour ce type de rendu. L’interactivité utilisateur avec la page est supposée. Il n’existe aucun concept de rendu côté client statique. CSR est supposé être interactif, de sorte que le « rendu interactif côté client » et « CSR interactif » ne sont pas utilisés par le secteur ou dans la documentation Blazor.

  • Le rendu côté serveur signifie que le balisage HTML final est généré par le runtime ASP.NET Core sur le serveur. Le code HTML est envoyé au client via un réseau pour l’affichage par le navigateur du client. Aucune interface utilisateur générée par le serveur de l’application n’est créée par le client pour ce type de rendu. Les SSR peuvent être de deux types :

    • SSR statique : le serveur produit du code HTML statique qui ne fournit pas d’interactivité utilisateur ou de maintenance de l’état du composant Razor.
    • SSR interactif : les événements Blazor autorisent l’interactivité des utilisateurs et l’état des composants Razor est géré par l’infrastructure Blazor.

  • Le prérendu est le processus de rendu initial du contenu d’une page sur le serveur sans activation des gestionnaires d’événements pour les contrôles rendus. Le serveur génère l’interface utilisateur HTML de la page dès que possible en réponse à la demande initiale, ce qui rend l’application plus réactive pour les utilisateurs. Le prérendu peut aussi améliorer l’optimisation du référencement d’un site auprès d’un moteur de recherche (SEO) en rendant le contenu de la réponse HTTP initiale qui est utilisée par les moteurs de recherche pour calculer le rang de la page. La préversion est toujours suivie du rendu final, soit sur le serveur, soit sur le client.

Composants Razor

Les applications Blazor sont basées sur les composants Razor, souvent appelés simples composants. Un composant est un élément d’interface utilisateur, comme une page, une boîte de dialogue ou un formulaire de saisie de données. Les composants sont des classes .NET C# intégrées dans des assemblys .NET.

Razor fait référence à la façon dont les composants sont généralement écrits sous la forme d’une page de balisage Razor pour la logique et la composition de l’interface utilisateur côté client. Razor est une syntaxe qui combine des balises HTML à du code C# destiné à améliorer la productivité des développeurs. Les fichiers Razor utilisent l’extension de fichier .razor.

Bien que certains développeurs Blazor et ressources en ligne utilisent le terme « composants Blazor », la documentation évite ce terme et utilise universellement « composants Razor » ou « composants ».

La documentation Blazor adopte plusieurs conventions pour afficher les composants et en discuter :

  • En règle générale, les exemples respectent les conventions de codage ASP.NET Core/C# et les directives d’ingénierie. Pour plus d’informations, consultez les ressources suivantes :
  • Le code de projet, les noms et chemins de fichiers, les noms de modèles de projet et d’autres termes spécialisés sont en anglais (États-Unis) et sont généralement délimités par du code.
  • Les composants sont généralement référencés par leur nom de classe C# (casse Pascal) précédé du mot « composant ». Par exemple, un composant de chargement de fichiers standard est référencé en tant que « composant FileUpload ».
  • En règle générale, le nom de classe C# d’un composant est le même que son nom de fichier.
  • En règle générale, un composant routable définit son URL relative comme le nom de classe du composant dans la casse kebab. Par exemple, un composant FileUpload inclut une configuration de routage pour atteindre le composant rendu à l’URL relative /file-upload. Le routage et la navigation sont couverts dans Routage et navigation ASP.NET Core Blazor.
  • Quand plusieurs versions d’un composant sont utilisées, elles sont numérotées séquentiellement. Par exemple, le composant FileUpload3 est accessible à /file-upload-3.
  • Les directives Razor dans la partie supérieure d’une définition de composant (.razor file) sont placées dans l’ordre suivant : @page, @rendermode (.NET 8 ou version ultérieure), instructions @using, autres directives par ordre alphabétique.
  • Bien qu’ils ne soient pas obligatoires pour les membres private, les modificateurs d’accès sont utilisés dans des exemples d’articles et des exemples d’applications. Par exemple, private est mentionné pour la déclaration d’un champ nommé maxAllowedFiles en tant que private int maxAllowedFiles = 3;.
  • Les valeurs de paramètres de composant commencent par un symbole @ réservé à Razor, mais ce n’est pas obligatoire. Les littéraux (par exemple, valeurs booléennes), mots clés (par exemple, this) et valeurs null utilisés comme valeurs de paramètres de composant n’ont pas le préfixe @, mais il s’agit là aussi d’une simple convention de documentation. Dans votre code, vous pouvez faire précéder les littéraux du préfixe @ si vous le souhaitez.
  • Les classes C# utilisent le mot clé this et évitent de préfixer des champs avec un trait de soulignement (_) qui sont affectés aux constructeurs, ce qui diffère des directives d’ingénierie de l’infrastructure ASP.NET Core.
  • Dans des exemples qui utilisent des constructeurs principaux (C# 12 ou version ultérieure), les paramètres du constructeur principal sont généralement utilisés directement par les membres de classe.

Vous trouverez des informations supplémentaires sur la syntaxe des composants Razor dans la section Syntaxe Razor des composants Razor ASP.NET Core.

Voici un exemple de composant de compteur et une partie d’une application créée à partir d’un modèle de projet Blazor. La couverture détaillée des composants se trouve dans les articles Composants plus loin dans la documentation. L’exemple suivant illustre les concepts de composant rencontrés dans les articles Notions de base avant d’atteindre les articles Composants, plus loin dans la documentation.

Counter.razor:

Le composant suppose que le mode d’affichage interactif est hérité d’un composant parent ou appliqué globalement à l’application.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Le composant suppose que le mode d’affichage interactif est hérité d’un composant parent ou appliqué globalement à l’application.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Le composant Counter précédent :

  • Définit sa route avec la directive @page dans la première ligne.
  • Définit son titre de page et son titre.
  • Affiche le nombre actuel avec @currentCount. currentCount est une variable entière définie dans le code C# du bloc @code.
  • Affiche un bouton pour déclencher la méthode IncrementCount, qui figure également dans le bloc @code et augmente la valeur de la variable currentCount.

Modes de rendu

Les articles du nœud Principes de base font référence au concept de modes de rendu. Ce sujet est abordé en détail dans l’article Modes de rendu ASP.NET Core Blazor dans le nœud Composants, qui apparaît après le nœud d’articles Principes de base.

Pour les premières références de ce nœud d’articles pour afficher les concepts du mode, notez simplement ce qui suit à ce stade :

Chaque composant d’une Blazor Web App adopte un mode de rendu pour déterminer le modèle d’hébergement qu’il utilise, où il est rendu, et s’il est rendu statiquement sur le serveur, rendu pour l’interactivité utilisateur sur le serveur ou rendu pour l’interactivité utilisateur sur le client (généralement avec prérendu sur le serveur).

Les applications Blazor Server et Blazor WebAssembly pour les versions ASP.NET Core antérieures à .NET 8 restent fixées sur les concepts du modèle d’hébergement, et non sur les modes de rendu. Les modes de rendu sont appliqués conceptuellement aux Blazor Web App dans .NET 8 ou une version ultérieure.

Le tableau suivant présente les modes de rendu disponibles pour le rendu des composants Razor dans une Blazor Web App. Les modes de rendu sont appliqués aux composants avec la directive @rendermode sur l'instance du composant ou sur la définition du composant. Il est également possible de définir un mode de rendu pour l’ensemble de l’application.

Nom Description Emplacement du rendu Interactive
Serveur statique Rendu statique côté serveur (SSR statique) Serveur
Serveur interactif Rendu interactif côté serveur (SSR interactif) à l’aide de Blazor Server Serveur
WebAssembly interactif Rendu côté client (CSR) à l’aide de Blazor WebAssembly† Client
Voiture interactive SSR interactif à l’aide de Blazor Server dans un premier temps, puis de CSR lors des visites ultérieures après le téléchargement de l’offre groupée Blazor Serveur, puis client

† Le rendu côté client (CSR) est supposé être interactif. Le « rendu interactif côté client » et « CSR interactif » ne sont pas utilisés par le secteur ou dans la documentation Blazor.

Les informations précédentes sur les modes de rendu sont tout ce que vous devez savoir pour comprendre les articles du nœud Principes de base. Si vous débutez avec Blazor et lisez les articles Blazor dans l’ordre dans la table des matières, vous pouvez retarder l’utilisation d’informations détaillées sur les modes de rendu jusqu’à atteindre l’article des modes de rendu ASP.NET Core Blazor dans le nœud Composants.

DOM (Document Object Model)

En référence au Document Object Model, utilisez l’abréviation DOM.

Pour plus d'informations, reportez-vous aux ressources suivantes :

Sous-ensemble d’API .NET pour les applications Blazor WebAssembly

Il n’existe pas de liste exhaustive des API .NET spécifiques qui sont prises en charge sur le navigateur pour Blazor WebAssembly. Vous pouvez cependant rechercher manuellement une liste d’API .NET annotées avec [UnsupportedOSPlatform("browser")] pour découvrir les API .NET qui ne sont pas prises en charge dans WebAssembly.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Pour plus d’informations, consultez les ressources suivantes :

Exemples d’applications

Des exemples d’applications de documentation sont disponibles pour inspection et téléchargement :

Blazor exemples de dépôt GitHub (dotnet/blazor-samples)

Recherchez un exemple d’application en sélectionnant d’abord le dossier de version qui correspond à la version de .NET avec laquelle vous travaillez.

Exemples d’applications dans le référentiel :

Ce référentiel d’exemples contient deux types d’exemples :

  • Les exemples d’applications de l’extrait de code fournissent les exemples de code qui s’affichent dans les articles. Ces applications compilent, sans être nécessairement exécutables. Ces applications sont utiles pour obtenir simplement l’exemple de code apparaissant dans les articles.
  • Les exemples d’applications conçus pour accompagner les articles Blazor sont compilés et s’exécutent pour les scénarios suivants :
    • Blazor Server avec EF Core
    • Blazor Server et Blazor WebAssembly avec SignalR
    • Journalisation activée pour les étendues Blazor WebAssembly

Pour plus d’informations et une liste des exemples dans le référentiel, consultez le Blazor dépôt GitHub d’exemples README.md fichier.

L’application de test de base du référentiel ASP.NET Core est également un ensemble d’exemples utiles pour différents scénarios Blazor :

BasicTestApp dans la source de référence ASP.NET Core (dotnet/aspnetcore)

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Pour télécharger les exemples d’applications :

Multiples d’octets

Les tailles d’octets .NET utilisent des préfixes de métrique pour les multiples non décimaux d’octets en fonction de puissances de 1024.

Nom (abréviation) Size Exemple
Kilo-octet (Ko) 1 024 octets 1 Ko = 1 024 octets
Mégaoctet (Mo) 1 0242 octets 1 Mo = 1 048 576 octets
Gigaoctet (Go) 1 0243 octets 1 Go = 1 073 741 824 octets

Demandes de support

Seuls les problèmes liés à la documentation sont appropriés pour le dépôt dotnet/AspNetCore.Docs. Pour la prise en charge des produits, n’ouvrez pas de problème de documentation. Demandez de l’aide par un ou plusieurs des canaux de support suivants :

Pour un bogue potentiel dans l’infrastructure ou les commentaires sur les produits, ouvrez un problème pour l’unité de produit ASP.NET Core dans Problèmes dotnet/aspnetcore. Les rapports de bogues nécessitent généralement les éléments suivants :

  • Une explication claire du problème : suivez les instructions du modèle de problème GitHub fourni par l’unité de produit lors de l’ouverture du problème.
  • Un projet de reproduction minimal : placez un projet sur GitHub que les ingénieurs de l’unité de produit pourront télécharger et exécuter. Placez un lien croisé vers le projet dans le commentaire d’ouverture du problème.

Pour un problème potentiel avec un article Blazor, ouvrez un problème de documentation. Pour signaler un problème de documentation, utilisez le lien de commentaires Ouvrir un problème de documentation en bas de l’article. Les métadonnées ajoutées à votre problème fournissent des données de suivi et envoient un ping automatique à l’auteur de l’article. Si le sujet a été discuté avec l’unité de produit avant l’ouverture du problème de documentation, placez un lien croisé vers le problème d’ingénierie dans le commentaire d’ouverture du problème de documentation.

Pour des problèmes ou des commentaires sur Visual Studio, utilisez le Signaler un problème ou suggérer des mouvements de fonctionnalité à partir de Visual Studio, qui ouvrent des problèmes internes pour Visual Studio. Pour plus d'informations, consultez Commentaires Visual Studio.

Pour les problèmes liés à Visual Studio Code, demandez de l’aide sur les forums de support de la communauté. Pour obtenir des rapports de bogues et des commentaires sur les produits, ouvrez un problème dans le dépôt GitHub microsoft/vscode.

Les problèmes GitHub pour la documentation Blazor sont automatiquement marqués pour le triage sur le projet Blazor.Docs (dépôt GitHub dotnet/AspNetCore.Docs). Patientez un peu avant d’obtenir une réponse, en particulier pendant les week-ends et les jours fériés. En règle générale, les auteurs de documentation répondent dans les 24 h les jours de semaine.

Pour voir l’ensemble des liens vers les ressources Blazor gérées par la communauté, visitez Awesome Blazor.

Remarque

Microsoft ne possède pas, ne tient pas à jour et ne prend pas en charge Awesome Blazor ni la plupart des produits et services de la communauté décrits et accessibles ici.