Notions de base d’ASP.NET Core Blazor

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 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 :
  • Directives d’ingénierie de l’infrastructure ASP.NET Core (référentiel GitHub dotnet/aspnetcore)
  • Conventions de codage C# (Guide C#)
• 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 :

@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.

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 :

• Présentation du DOM (documentation MDN)
• Spécification du Document Object Model de niveau 1 (W3C)

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.

Pour plus d’informations, consultez les ressources suivantes :

• Bibliothèques de classes : Analyseur de compatibilité du navigateur côté client
• Annotation des API comme étant non prises en charge sur des plateformes spécifiques (dotnet/designsdépôt GitHub)

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.

Pour plus d’informations, consultez les Blazor exemples du référentiel GitHub fichier README.md.

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)

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

• Télécharger le fichier ZIP du Blazorréférentiel d’échantillons.
• Décompressez le fichier .

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.

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 :

• Dépassement de capacité de la pile (étiqueté : blazor)
• Équipe générale ASP.NET Core Slack
• Gitter Blazor

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.

Liens de la communauté vers les ressources Blazor

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