principes fondamentaux de 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 se produire sur le client ou du 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 que les navigateurs affichent.

• Client-side rendering (CSR) signifie que le balisage HTML final est généré par le runtime webAssembly .NET sur le client. Aucune interface utilisateur HTML générée côté client pour l'application n'est envoyée depuis 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.

• Server-side rendering (SSR) 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. Aucun HTML pour l'interface utilisateur générée par le serveur de l'application n'est créé 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 initial de rendu du contenu d'une page sur le serveur, sans activation des gestionnaires d'événements pour les contrôles déjà 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 rendu anticipé peut aussi améliorer l'optimisation du référencement (SEO) d'un site, en fournissant le contenu pour la réponse HTTP initiale, que les moteurs de recherche utilisent pour calculer le classement 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 C# .NET intégrées aux 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 :
  • ASP.NET Core directives d’ingénierie du framework (référentiel dotnet/aspnetcore GitHub)
  • Conventions de codage C# (Guide C#)
• Codes de projet, chemins d’accès et noms de fichiers, noms de modèles de projet et d’autres termes spécialisés sont en anglais des États-Unis et sont généralement placés dans des balises de 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 général, les composants routables définissent leurs URL relatives en utilisant le nom de classe du composant en 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 ASP.NET Core Blazor routage.
• 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.
• Razor directives en haut d’une définition de composant (.razor file) sont placées dans l’ordre suivant : @page, @rendermode (.NET 8 ou version ultérieure), @using instructions, d’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 Razor réservé à @, 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 les champs de préfixe avec un trait de soulignement (_) attribués aux constructeurs, qui diffèrent des instructions 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. Dans les exemples de l'article, les lignes de code sont divisées pour réduire le défilement horizontal. Ces coupures n'affectent pas l'exécution mais peuvent être supprimées lors du collage dans votre projet.

Des informations supplémentaires sur la syntaxe du composant Razor sont fournies dans la syntaxe Razor des composants ASP.NET Core Razor.

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"

<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 en-tête.
• 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

Une liste organisée d'API de .NET spécifiques prises en charge dans le navigateur pour Blazor WebAssembly n'est pas disponible. Toutefois, vous pouvez manuellement rechercher pour obtenir la liste des API .NET annotées avec [UnsupportedOSPlatform("browser")] pour découvrir les API .NET qui ne sont pas prises en charge par WebAssembly.

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

• Bibliothèques de classes : Analyseur de compatibilité du navigateur côté client
• Annotation d’API non prises en charge sur des plateformes spécifiques (référentiel dotnet/designs GitHub

Exemples d’applications

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

Blazor référentiel GitHub d'exemples (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.

Les exemples d’applications contiennent uniquement un sous-ensemble d’exemples d’articles pour Blazor les démonstrations de fonctionnalités. Lorsqu’un exemple de code présenté par un article ne se trouve pas dans un ou plusieurs des exemples d’applications, vous pouvez généralement placer l’exemple de code dans une application de test locale pour une démonstration.

Pour plus d’informations, une liste des exemples dans le référentiel et des instructions de téléchargement, consultez le fichier README du référentiel Blazor GitHub des exemples.

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

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

Multiples d’octets

. Les tailles d'octet .NET utilisent des préfixes métriques pour les multiples non décimaux d'octets en fonction des 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 :

• Stack Overflow (étiqueté : blazor)
• General ASP.NET Core Slack Team
• Gitter Blazor

Pour un bogue potentiel dans le framework ou les retours sur le produit, signalez un problème pour l’unité de produit ASP.NET Core sur dotnet/aspnetcore issues. Les rapports de bogues nécessitent généralement les éléments suivants :

• Explication 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.
• Projet de repro minimal : placez un projet sur GitHub à l'intention des ingénieurs de l'unité produit pour qu'ils puissent le télécharger et l'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 concernant Visual Studio, utilisez les options Signaler un problème ou Suggérer une fonctionnalité depuis Visual Studio pour ouvrir des problèmes internes de Visual Studio. Pour plus d’informations, consultez Visual Studio Commentaires.

Pour des problèmes avec Visual Studio Code, demandez de l’aide sur les forums de soutien de la communauté. Pour les rapports de bogues et les commentaires sur les produits, ouvrez un problème sur le microsoft/vscode GitHub référentiel.

Les problèmes de documentation GitHub Blazor sont automatiquement marqués pour triage dans 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.