Ferramentas para ASP.NET Core Blazor

Artigo
09/30/2024

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Este artigo descreve as ferramentas para a criação de aplicativos do Blazor usando várias ferramentas:

Visual Studio (VS): O ambiente de desenvolvimento integrado (IDE) mais abrangente para desenvolvedores do .NET no Windows. Inclui uma variedade de ferramentas e recursos para elevar e aprimorar cada estágio do desenvolvimento de software.
O Visual Studio Code (VS Code) é um editor de código multiplataforma de software livre que pode ser usado para desenvolver aplicativos do Blazor.
CLI do .NET: A interface de linha de comando (CLI) do .NET é uma cadeia de ferramentas multiplataforma para desenvolver, criar, executar e publicar aplicativos .NET. A CLI do .NET está incluída no SDK do .NET e é executada em qualquer plataforma compatível com o SDK.

Selecione o pivô deste artigo que corresponde à sua escolha de ferramentas.

Para criar um aplicativo do Blazor com o Visual Studio, use as seguintes diretrizes:

Instale a última versão do Visual Studio com a carga de trabalho ASP.NET e desenvolvimento para a Web.
Crie um novo projeto utilizando um dos modelos Blazor disponíveis:
- Blazor Web App: cria um aplicativo Web do Blazor compatível com a SSR interativa (renderização interativa do lado do servidor) e com a CSR (renderização do lado do cliente). O modelo do Blazor Web App é recomendado como uma introdução ao Blazor para aprender sobre recursos do Blazor do lado do servidor e do cliente.
- Blazor WebAssembly Aplicativo Autônomo: cria um aplicativo Web cliente autônomo que pode ser implantado como um site estático.

Selecione Avançar.

Instale a última versão do Visual Studio com a carga de trabalho ASP.NET e desenvolvimento para a Web.
Crie um novo projeto:
- Para uma experiência Blazor Server, escolha o modelo de Aplicativo Blazor Server, que inclui código de demonstração e Bootstrap, ou o modelo de Aplicativo vazio Blazor Server sem código de demonstração e Bootstrap. Selecione Avançar.
- Para uma experiência Blazor WebAssembly autônoma, escolha o modelo de Blazor WebAssemblyAplicativo, que inclui código de demonstração e Bootstrap, ou o modelo de Blazor WebAssemblyAplicativo vazio sem código de demonstração e Bootstrap. Selecione Avançar.

Instale a última versão do Visual Studio com a carga de trabalho ASP.NET e desenvolvimento para a Web.
Crie um novo projeto:
- Para uma experiência Blazor Server, escolha o modelo de Aplicativo Blazor Server. Selecione Avançar.
- Para uma experiência Blazor WebAssembly, escolha o modelo de Aplicativo Blazor WebAssembly. Selecione Avançar.

Forneça um Nome de projeto e confirme se o Local está correto.
Para obter mais informações sobre as opções na caixa de diálogo Informações adicionais, consulte a seção Blazormodelos de projeto e opções de modelo.

Observação

O modelo de projeto Blazor WebAssembly hospedado não está disponível no ASP.NET Core 8.0 ou posterior. Para criar um aplicativo Blazor WebAssembly hospedado, uma opção de Estrutura anterior ao .NET 8.0 deve ser selecionada com a caixa de seleção ASP.NET Core hospedado.

Para um aplicativo hospedadoBlazor WebAssembly, selecione a caixa de seleção ASP.NET Hospedado na caixa de diálogo Informações adicionais.

Selecione Criar.

O Visual Studio Code é um IDE (Ambiente de Desenvolvimento Integrado) de código aberto e multiplataforma que pode ser usado para desenvolver aplicativos Blazor.

Instale a versão mais recente do Visual Studio Code para sua plataforma.

Instale o Kit de Desenvolvimento do C# para Visual Studio Code. Para obter mais informações, consulte Depuração de aplicativos ASP.NET Core Blazor.

Se você for novo no VS Code, consulte a Documentação do VS Code. Se você não estiver familiarizado com o SDK do .NET, consulte O que é o SDK do .NET? e os artigos associados na documentação do SDK do .NET.

Crie um novo projeto:

Abra o VS Code.
Vá para o modo de exibiçãoExplorador e selecione o botão Criar Projeto do .NET. Como alternativa, você pode abrir a Paleta de Comandos usando Ctrl+Shift+Pe, em seguida, digite ".NET" e localize e selecione o comando .NET: Novo Projeto.
Selecione o modelo de projeto Blazor na lista.
Na caixa de diálogo Local do Projeto, crie ou selecione uma pasta para o projeto.
Na Paleta de Comandos, forneça um nome para o projeto ou aceite o nome padrão.
Selecione Criar projeto para criar o projeto ou ajustar as opções do projeto selecionando Mostrar todas as opções de modelo. Para obter mais informações sobre os modelos e opções, consulte a seção Blazormodelos de projeto e opções de modelo.
Pressione F5 no teclado para executar o aplicativo com o depurador ou Ctrl+F5 para executar o aplicativo sem o depurador.

A Paleta de Comandos pede que você selecione um depurador. Selecione C# na lista.

Em seguida, selecione a configuração de inicialização de https.
Para interromper o aplicativo, pressione Shift+F5 no teclado.

As instruções do Visual Studio Code (VS Code) para o desenvolvimento do ASP.NET Core em algumas partes da documentação do Blazor usam a CLI do.NET, que faz parte do SDK do .NET. Os comandos da CLI do .NET são emitidos no Terminal integrado do VS Code, que usa um shell de comando do PowerShell como padrão. O Terminal é aberto selecionando Novo Terminal no menu Terminal na barra de menus.

Para obter mais informações sobre a configuração e o uso do Visual Studio Code, consulte a documentação do Visual Studio Code.

Configuração de inicialização e tarefa Blazor WebAssembly hospedada

Para soluçõessoluções Blazor WebAssemblyhospedadas, adicione (ou mova) a pasta .vscode com arquivos launch.json e tasks.json na pasta pai da solução, que é a pasta que contém as pastas típicas do projeto: Client, Server e Shared. Atualize ou confirme se a configuração nos arquivos launch.json e tasks.json executa um aplicativo hospedado Blazor WebAssembly do projeto Server.

Examine o arquivo Properties/launchSettings.json e determine a URL do aplicativo da propriedade applicationUrl. Dependendo da versão da estrutura, o protocolo de URL é seguro (HTTPS) https://localhost:{PORT} ou não seguro (HTTP) http://localhost:{PORT}, em que o espaço reservado {PORT} é uma porta atribuída. Observe a URL para uso no arquivo launch.json.

Na configuração de inicialização do arquivo .vscode/launch.json:

Defina o diretório de trabalho atual (cwd) para a pasta do projeto Server.
Indique a URL do aplicativo com a propriedade url. Use o valor registrado anteriormente do arquivo Properties/launchSettings.json.

"cwd": "${workspaceFolder}/{SERVER APP FOLDER}",
"url": "{URL}"

Na configuração anterior:

O espaço reservado {SERVER APP FOLDER} é a pasta do projeto Server, normalmente Server.
O espaço reservado {URL} é a URL do aplicativo, que é especificada no arquivo do aplicativo Properties/launchSettings.json na propriedade applicationUrl.

Se o Google Chrome for preferível em relação ao Microsoft Edge, atualize ou adicione uma propriedade adicional de "browser": "chrome" à configuração.

No arquivo de exemplo .vscode/launch.json a seguir:

Define o diretório de trabalho atual como a pasta Server.
Define a URL do aplicativo como http://localhost:7268.
Altera o navegador padrão do Microsoft Edge para o Google Chrome.

"cwd": "${workspaceFolder}/Server",
"url": "http://localhost:7268",
"browser": "chrome"

O arquivo .vscode/launch.json completo:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "blazorwasm",
      "name": "Launch and Debug Blazor WebAssembly Application",
      "request": "launch",
      "cwd": "${workspaceFolder}/Server",
      "url": "http://localhost:7268",
      "browser": "chrome"
    }
  ]
}

No .vscode/tasks.json, adicione um argumento build que especifica o caminho para o arquivo de projeto do aplicativo Server:

"${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj",

No argumento anterior:

O espaço reservado {SERVER APP FOLDER} é a pasta do projeto Server, normalmente Server.
O espaço reservado {PROJECT NAME} é o nome do aplicativo, normalmente com base no nome da solução seguido por .Server em um aplicativo gerado a partir do modelo de projeto Blazor WebAssembly.

Um arquivo de exemplo .vscode/tasks.json com um projeto Server chamado BlazorHosted na pasta Server da solução:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
        "args": [
          "build",
          "${workspaceFolder}/Server/BlazorHosted.Server.csproj",
          "/property:GenerateFullPaths=true",
          "/consoleloggerparameters:NoSummary",
        ],
        "group": "build",
        "presentation": {
          "reveal": "silent"
        },
        "problemMatcher": "$msCompile"
    }
  ]
}

Observação

No momento, há suporte somente a depuração do navegador.

Não é possível recompilar automaticamente o aplicativo Server de back-end de uma solução Blazor WebAssembly hospedada durante a depuração, por exemplo, executando o aplicativo com dotnet watch run.

.vscode/launch.json (configuração launch):

...
"cwd": "${workspaceFolder}/{SERVER APP FOLDER}",
...

Na configuração anterior do diretório de trabalho atual (cwd), o espaço reservado {SERVER APP FOLDER} é a pasta do projeto Server, normalmente "Server".

Se o Microsoft Edge for usado e o Google Chrome não estiver instalado no sistema, adicione uma propriedade adicional de "browser": "edge" à configuração.

Exemplo para uma pasta de projeto de Server e que gera o Microsoft Edge como o navegador para execuções de depuração em vez do navegador padrão Google Chrome:

...
"cwd": "${workspaceFolder}/Server",
"browser": "edge"
...

.vscode/tasks.json (argumentos de comando dotnet):

...
"${workspaceFolder}/{SERVER APP FOLDER}/{PROJECT NAME}.csproj",
...

No argumento anterior:

O espaço reservado {SERVER APP FOLDER} é a pasta do projeto Server, normalmente "Server".
O espaço reservado {PROJECT NAME} é o nome do aplicativo, normalmente com base no nome da solução seguido por ".Server" em um aplicativo gerado a partir do modelo de projeto Blazor.

O exemplo a seguir do tutorial para usar SignalR com um aplicativo Blazor WebAssembly usa um nome de pasta de projeto e Server um nome de projeto de BlazorWebAssemblySignalRApp.Server:

...
"args": [
  "build",
    "${workspaceFolder}/Server/BlazorWebAssemblySignalRApp.Server.csproj",
    ...
],
...

O .NET SDK é um conjunto de bibliotecas e ferramentas que os desenvolvedores usam para criar aplicativos e bibliotecas .NET.

Instale o SDK do .NET. Os comandos são emitidos em um shell de comando usando a CLI do .NET.

Se você instalou anteriormente um ou mais SDKs do .NET e deseja ver sua versão ativa, execute o seguinte comando em um shell de comando:

dotnet --version

Se você não estiver familiarizado com o SDK do .NET, consulte O que é o SDK do .NET? e os artigos associados na documentação do SDK do .NET.

Crie um novo projeto:

Altere para o diretório, usando o comando cd, no qual você deseja criar a pasta do projeto (por exemplo, cd c:/users/Bernie_Kopell/Documents).
Para uma experiência de Blazor Web App com SSR interativa (renderização interativa do lado do servidor) padrão, execute o seguinte comando:
```
dotnet new blazor -o BlazorApp
```
Para uma experiência Blazor WebAssembly autônoma, execute o seguinte comando em um shell de comando que utiliza o modelo blazorwasm:
```
dotnet new blazorwasm -o BlazorApp
```

Crie um novo projeto:

Altere para o diretório, usando o comando cd, no qual você deseja criar a pasta do projeto (por exemplo, cd c:/users/Bernie_Kopell/Documents).
Para obter uma experiência Blazor Server com código de demonstração e Bootstrap, execute o seguinte comando:
```
dotnet new blazorserver -o BlazorApp
```
Para obter uma experiência Blazor WebAssembly autônoma com código de demonstração e Bootstrap, execute o seguinte comando:
```
dotnet new blazorwasm -o BlazorApp
```
Para uma experiência Blazor WebAssembly hospedada com código de demonstração e Bootstrap, adicione a opção hospedada (-ho/--hosted) ao comando:
```
dotnet new blazorwasm -o BlazorApp -ho
```
Observação

O modelo de projeto Blazor WebAssembly hospedado não está disponível no ASP.NET Core 8.0 ou posterior. Para criar um aplicativo Blazor WebAssembly hospedado usando um SDK do .NET 8.0 ou posterior, passe a opção -f|--framework com uma estrutura de destino 7.0 (net7.0):
```
dotnet new blazorwasm -o BlazorApp -ho -f net7.0
```

Crie um novo projeto:

Altere para o diretório, usando o comando cd, no qual você deseja criar a pasta do projeto (por exemplo, cd c:/users/Bernie_Kopell/Documents).
Para uma experiência Blazor WebAssembly, execute o seguinte comando:
```
dotnet new blazorwasm -o BlazorApp
```
Para uma experiência Blazor WebAssembly hospedada, adicione a opção hospedada (-ho ou --hosted) ao comando:
```
dotnet new blazorwasm -o BlazorApp -ho
```
Observação

O modelo de projeto Blazor WebAssembly hospedado não está disponível no ASP.NET Core 8.0 ou posterior. Para criar um aplicativo Blazor WebAssembly hospedado usando um SDK do .NET 8.0 ou posterior, passe a opção -f|--framework com o moniker da estrutura de destino (por exemplo, net6.0):
```
dotnet new blazorwasm -o BlazorApp -ho -f net6.0
```
Para uma experiência Blazor Server, execute o seguinte comando:
```
dotnet new blazorserver -o BlazorApp
```

Para obter mais informações sobre os modelos e opções, consulte a seção Blazormodelos de projeto e opções de modelo.

Executar o aplicativo

Importante

Ao executar um Blazor Web App, execute o aplicativo no projeto do servidor da solução, que é o projeto com um nome que não termina em .Client.

Importante

Ao executar um aplicativo Blazor WebAssembly hospedado, execute o aplicativo no projeto de Server da solução.

Pressione Ctrl+F5 no teclado para executar o aplicativo sem o depurador.

O Visual Studio exibe a seguinte caixa de diálogo quando um projeto ainda não está configurado para usar o SSL:

Caixa de diálogo Criar um certificado autoassinado

Selecione Sim se você confiar no certificado SSL do ASP.NET Core.

A seguinte caixa de diálogo é exibida:

Caixa de diálogo de aviso de segurança

Selecione Sim para reconhecer o risco e instalar o certificado.

Visual Studio:

Compila e executa o aplicativo.
Inicia o navegador padrão em https://localhost:{PORT}, que exibe a interface do usuário dos aplicativos. O espaço reservado {PORT} é a porta aleatória atribuída na criação do aplicativo. Se você precisar alterar a porta devido a um conflito de porta local, altere a porta no arquivo Properties/launchSettings.json do projeto.

No Visual Studio Code, pressione Ctrl+F5 (Windows) ou ⌘+F5 (macOS) para executar o aplicativo sem depuração.

No prompt Selecionar depurador na Paleta de Comandos na parte superior da interface do usuário do VS Code, selecione C#. No próximo prompt, selecione o perfil HTTPS ([https]).

O navegador padrão é iniciado em https://localhost:{PORT}, que exibe a interface do usuário do aplicativo. O espaço reservado {PORT} é a porta aleatória atribuída na criação do aplicativo. Se você precisar alterar a porta devido a um conflito de porta local, altere a porta no arquivo Properties/launchSettings.json do projeto.

Em um shell de comando aberto na pasta raiz do projeto, execute o comando dotnet watch para compilar e iniciar o aplicativo:

dotnet watch

Quando um aplicativo criado a partir do modelo de projeto do Blazor Web App é executado com a CLI do .NET, o aplicativo é executado em um ponto de extremidade HTTP (inseguro) porque o primeiro perfil encontrado no arquivo de configurações de inicialização do aplicativo (Properties/launchSettings.json) é o perfil HTTP (inseguro), que é chamado http. O perfil HTTP foi colocado na primeira posição para facilitar a transição da adoção da segurança SSL/HTTPS para usuários que não são do Windows.

Uma abordagem para executar o aplicativo com SSL/HTTPS é passar a -lp|--launch-profile opção com o nome do perfil https para o comando dotnet watch:

dotnet watch -lp https

Uma abordagem alternativa é mover o perfil https acima do perfil http no arquivo Properties/launchSettings.json e salvar a alteração. Depois de alterar a ordem do perfil no arquivo, o comando dotnet watch sempre usa o perfil https por padrão.

Pare o aplicativo

Pare o aplicativo usando uma das seguintes abordagens:

Feche a janela do navegador.
No Visual Studio:
- Use o botão Parar na barra de menus do Visual Studio:
- Pressione Shift+F5 no teclado.

Pare o aplicativo usando a seguinte abordagem:

Feche a janela do navegador.
No VS Code:
- No menu Executar, selecione Parar Depuração.
- Pressione Shift+F5 no teclado.

Pare o aplicativo usando a seguinte abordagem:

Feche a janela do navegador.
No shell de comando, pressione Ctrl+C (Windows) ou ⌘+C (macOS).

Arquivo de solução do Visual Studio (`.sln`)

Uma solução é um contêiner para organizar um ou mais projetos de código relacionados. Os arquivos de solução usam um formato exclusivo e não se destinam a serem editados diretamente.

O Visual Studio e o Visual Studio Code (VS Code) usam um arquivo de solução (.sln) para armazenar as configurações de uma solução. A CLI do .NET não organiza projetos usando um arquivo de solução, mas pode criar arquivos de solução e listar/modificar os projetos em arquivos de solução por meio do dotnet sln comando. Outros comandos da CLI do .NET usam o caminho do arquivo de solução para vários comandos de publicação, teste e empacotamento.

Em toda a documentação Blazor, a solução é usada para descrever os aplicativos criados a partir do modelo de projeto Blazor WebAssembly com a opção ASP.NET Core Hospedado habilitada ou de um modelo de projeto Blazor Hybrid. Os aplicativos produzidos a partir desses modelos de projeto incluem um arquivo de solução (.sln). Para aplicativos Blazor WebAssembly hospedados em que o desenvolvedor não está usando o Visual Studio, o arquivo de solução pode ser ignorado ou excluído se não for usado com comandos da CLI do .NET.

Para saber mais, consulte os recursos a seguir:

Blazor modelos de projeto e opções de modelo

A estrutura Blazor fornece modelos para criar novos aplicativos. Os modelos são usados para criar novos projetos Blazor e soluções, independentemente da ferramenta que você selecionar para o desenvolvimento do Blazor (Visual Studio, Visual Studio Code ou a CLI (interface de linha de comando) do .NET):

Modelo de projeto do Blazor Web App: blazor
Blazor WebAssembly Modelo de projeto de aplicativo autônomo: blazorwasm

Modelos de projeto Blazor Server: blazorserver, blazorserver-empty
Modelos de projeto Blazor WebAssembly: blazorwasm, blazorwasm-empty

Modelo de projeto Blazor Server: blazorserver
Modelo de projeto Blazor WebAssembly: blazorwasm

Para obter mais informações sobre modelos de projeto Blazor, consulte Estrutura do projeto Blazor do ASP.NET Core.

Os termos e conceitos de renderização usados nas orientações a seguir são apresentados nas seções a seguir do artigo de visão geral dos Fundamentos:

Os modos de renderização são fornecidas pelo artigo Modos de renderização Blazor ASP.NET Core.

Modo de renderização interativo

A SSR interativa (renderização interativa do lado do servidor) é habilitada com a opção Servidor.
Para habilitar apenas a interatividade com a renderização do lado do cliente (CSR), selecione a opção WebAssembly.
Para habilitar os modos de renderização interativos e a capacidade de alternar automaticamente entre eles no runtime, selecione a opção do modo de renderização (automática) Auto (Servidor e WebAssembly).
Se a interatividade estiver definida como None, o aplicativo gerado não terá interatividade. O aplicativo só está configurado para renderização estática do lado do servidor.

Inicialmente, o modo de renderização automática interativa usa o SSR interativo enquanto o pacote e o runtime do aplicativo .NET são baixados no navegador. Após a ativação do runtime do WebAssembly .NET, o modo de renderização alterna para a renderização do WebAssembly Interativo.

O modelo do Blazor Web App habilita a SSR estática e a renderização interativa usando um único projeto. Se você também habilitar o CSR, o projeto inclui um projeto de cliente adicional (.Client) para seus componentes baseados no WebAssembly. A saída interna do projeto cliente é baixada para o navegador e executada no cliente. Todos os componentes que utilizam o WebAssembly ou os modos de renderização automática devem ser criados a partir do projeto cliente.

Importante

Ao usar um Blazor Web App, a maioria dos componentes de exemplo de documentação do Blazor requerem interatividade para funcionar e demonstrar os conceitos abordados pelos artigos. Ao testar um componente de exemplo fornecido por um artigo, certifique-se de que o aplicativo adote interatividade global ou de que o componente adote um modo de renderização interativo.

Local de interatividade

Opções de Local de interatividade:

Por página/componente: o padrão configura a interatividade por página ou por componente.
Global: essa opção configura a interatividade globalmente para todo o aplicativo.

O local da interatividade só poderá ser definido se Modo de renderização interativo não for None e a autenticação não estiver habilitada.

Páginas de Amostra

Para incluir páginas de exemplo e um layout com base no estilo Bootstrap, marque a caixa de seleção Incluir páginas de exemplo. Desabilite essa opção para projetos sem páginas de amostra e estilo Bootstrap.

Diretrizes adicionais sobre opções de modelo

Modos de renderização Blazor do ASP.NET Core
Os Modelos padrão do .NET para o novo artigo do dotnet na documentação do .NET Core:
- blazor
- blazorwasm
Passando a opção de ajuda (-h ou --help) para o comando da CLI dotnet new em um shell de comando:
- dotnet new blazor -h
- dotnet new blazorwasm -h

Para obter mais informações sobre as opções de modelo, consulte os seguintes recursos:

Os Modelos padrão do .NET para o novo artigo do dotnet na documentação do .NET Core:
- blazorserver (inclui blazorserver-empty opções)
- blazorwasm (inclui blazorwasm-empty opções)
Passando a opção de ajuda (-h ou --help) para o comando da CLI dotnet new em um shell de comando:
- dotnet new blazorserver -h
- dotnet new blazorserver-empty -h
- dotnet new blazorwasm -h
- dotnet new blazorwasm-empty -h

Para obter mais informações sobre as opções de modelo, consulte os seguintes recursos:

Os Modelos padrão do .NET para o novo artigo do dotnet na documentação do .NET Core:
- blazorserver
- blazorwasm
Passando a opção de ajuda (-h ou --help) para o comando da CLI dotnet new em um shell de comando:
- dotnet new blazorserver -h
- dotnet new blazorwasm -h

Compartilhar via

Ferramentas para ASP.NET Core Blazor

Executar o aplicativo

Pare o aplicativo

Arquivo de solução do Visual Studio (`.sln`)

Blazor modelos de projeto e opções de modelo

Modo de renderização interativo

Local de interatividade

Páginas de Amostra

Diretrizes adicionais sobre opções de modelo

Recursos adicionais

Recursos adicionais

Compartilhar via

Ferramentas para ASP.NET Core Blazor

Executar o aplicativo

Pare o aplicativo

Arquivo de solução do Visual Studio (.sln)

Blazor modelos de projeto e opções de modelo

Modo de renderização interativo

Local de interatividade

Páginas de Amostra

Diretrizes adicionais sobre opções de modelo

Recursos adicionais

Recursos adicionais

Arquivo de solução do Visual Studio (`.sln`)