Ferramentas para ASP.NET Core Blazor

  • Artigo

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.

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 criar aplicativos Blazor em várias plataformas. Selecione sua plataforma na parte superior deste artigo.

Para criar um Blazor aplicativo no Windows, 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 Aplicativo Web: cria um aplicativo Web Blazor que dá suporte à renderização interativa do lado do servidor (SSR interativa) e à renderização do lado do cliente (CSR). O modelo de Aplicativo Web Blazor é 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.

Observação

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.

  • Para um Blazor Aplicativo Web na caixa de diálogo Informações adicionais:

    • Lista suspensa Modo de renderização interativo

      • A renderização interativa do servidor está habilitada por padrão com a opção Servidor.
      • Para habilitar apenas a interatividade com a renderização do cliente, 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.

      Por padrão, o modelo de Aplicativo Web Blazor habilita o SSR estático e interativo 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.

      Para obter mais informações, consulte ASP.NET Core Blazor modos de renderização.

    • Lista suspensa Local de interatividade

      • Por página/componente: o padrão configura a interatividade por página ou por componente.
      • Global: selecionar 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.

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

    Para obter mais informações, consulte ASP.NET Core Blazor modos de renderização.

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

  • Selecione Criar.

  • Pressione Ctrl+F5 (Windows) ou ⌘+F5 (macOS) para executar o aplicativo.

Ao executar uma Blazor WebAssemblysolução hospedada no Visual Studio, o projeto de inicialização da solução é o projeto Server.

Para obter mais informações sobre como confiar no certificado de desenvolvimento HTTPS do ASP.NET Core, consulte Impor HTTPS no ASP.NET Core.

Importante

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

Quando o aplicativo é iniciado, somente o arquivo Properties/launchSettings.json no projeto Server é usado.

Para criar um aplicativo Blazor no Linux ou macOS, use as seguintes diretrizes:

Use a CLI (interface de linha de comando) do .NET para executar comandos em um shell de comando.

Instale a versão mais recente do SDK do .NET Core. Se você instalou o SDK anteriormente, poderá determinar sua versão instalada executando o seguinte comando:

dotnet --version

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.

Crie um novo projeto:

  • Para uma Blazor experiência de aplicativo Web com renderização interativa padrão do lado do servidor, execute o seguinte comando em um shell de comando que usa o modelo de projeto blazor:

    dotnet new blazor -o BlazorApp

    Para habilitar somente a renderização do lado do cliente, use a -int|--interactivity opção definida como WebAssembly:

    dotnet new blazor -o BlazorApp -int WebAssembly

    Para habilitar a renderização interativa do lado do servidor seguida pela renderização do lado do cliente, use a opção -int|--interactivity definida como Auto:

    dotnet new blazor -o BlazorApp -int Auto

    Se a interatividade estiver desabilitada definindo a opção -int|--interactivity como None, o aplicativo gerado não terá interatividade. O aplicativo só está configurado para renderização estática do lado do servidor:

    dotnet new blazor -o BlazorApp -int None

    O modo de renderização Automática Interativa usa inicialmente a renderização interativa do lado do servidor (SSR interativa), enquanto o pacote e o runtime do aplicativo .NET são baixados no navegador. Depois que o runtime do .NET WebAssembly é ativado, o modo de renderização alterna para o modo de renderização WebAssembly Interativo.

    Por padrão, o modelo do Aplicativo Web Blazor habilita a renderização estática e a renderização interativa do lado do servidor usando um único projeto. Se você também habilitar o modo de renderização WebAssembly Interativo, o projeto incluirá um projeto de cliente adicional (.Client) nos seus componentes baseados no WebAssembly. A saída interna do projeto cliente é baixada para o navegador e executada no cliente. Todos os componentes que usam os modos de renderização Interativa Webassembly ou interativa automática devem ser criados a partir do projeto cliente.

    Para obter mais informações, consulte ASP.NET Core Blazor modos de renderização.

    Por padrão, os aplicativos definem o local da interatividade por componente/página. Para estabelecer a interatividade em todo o aplicativo, utilize a opção -ai|--all-interactive:

    dotnet new blazor -o BlazorApp -ai

    Selecionar essa opção define a interatividade para todo o aplicativo no componente App, especificando um modo de renderização para os componentes HeadOutlet e Routes de nível superior. A configuração da interatividade nesses componentes propaga a interatividade para todos os componentes filhos do aplicativo.

    O local da interatividade só pode ser definido como se o modo de renderização interativa (-int|--interactivity) não for None e a autenticação não estiver habilitada.

    Para criar um aplicativo sem páginas de amostra e estilo, utilize a opção -e|--empty:

    dotnet new blazor -o BlazorApp -e

  • 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

    Para criar um aplicativo Blazor WebAssembly autônomo sem páginas de amostra e estilo, utilize a opção -e|--empty:

    dotnet new blazorwasm -o BlazorApp -e

Crie um novo projeto:

  • Para obter uma experiência Blazor Server com código de demonstração e Bootstrap, execute o seguinte comando:

    dotnet new blazorserver -o BlazorApp

  • Como alternativa, crie um Blazor Server aplicativo sem código de demonstração e Bootstrap usando o blazorserver-empty modelo do projeto:

    dotnet new blazorserver-empty -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

  • Como alternativa, crie um aplicativo Blazor WebAssembly autônomo sem código de demonstração e Bootstrap usando o blazorwasm-empty modelo do projeto:

    dotnet new blazorwasm-empty -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

  • Como alternativa, crie um aplicativo hospedado Blazor WebAssembly sem código de demonstração e Bootstrap usando o modelo blazorwasm-empty com a opção hospedada:

    dotnet new blazorwasm-empty -o BlazorApp -ho

Crie um novo projeto:

  • 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

  • Para uma experiência Blazor Server, execute o seguinte comando:

    dotnet new blazorserver -o BlazorApp

Abra a pasta BlazorApp no Visual Studio Code.

Quando o Visual Studio Code solicitar que você adicione ativos para compilar e depurar o projeto, selecione Sim.

Se o Visual Studio Code não se oferecer automaticamente para adicionar os ativos de compilação e depuração (a pasta .vscode com os arquivos launch.json e tasks.json), selecione Exibir>Paleta de Comandos e digite ".NET" na caixa de pesquisa. Na lista de comandos, selecione o comando ".NET: Generate Assets for Build and Debug".

Observação

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

O arquivo Properties/launchSettings.json do projeto inclui a propriedade inspectUri para o proxy de depuração para quaisquer perfis na seção profiles do arquivo:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",

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

Para soluçõessoluçõesBlazor 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.

Importante

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

Quando o aplicativo é iniciado, somente o arquivo Properties/launchSettings.json no projeto Server é usado.

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"
    }
  ]
}

Pressione Ctrl+F5 (Windows) ou ⌘+F5 (macOS) para executar o aplicativo.

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",
    ...
],
...

Pressione Ctrl+F5 (Windows) ou ⌘+F5 (macOS) para executar o aplicativo.

Confiar em um certificado de desenvolvimento

Para saber mais, confira Impor HTTPS no ASP.NET Core.

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

Uma solução é um contêiner para organizar um ou mais projetos de código relacionados. O Visual Studio usa um arquivo de solução (.sln) para armazenar as configurações de uma solução. Os arquivos de solução usam um formato exclusivo e não se destinam a serem editados diretamente.

As ferramentas fora do Visual Studio podem interagir com os arquivos de solução:

  • A CLI do .NET pode criar arquivos de solução e listar/modificar os projetos em arquivos de solução por meio do comando dotnet sln. Outros comandos da CLI do .NET usam o caminho do arquivo de solução para vários comandos de publicação, teste e empacotamento.
  • O Visual Studio Code pode executar o comando dotnet sln e outros comandos da CLI do .NET por meio de seu terminal integrado, mas não usa as configurações em um arquivo de solução diretamente.

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) por padrão. 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 obter mais informações, consulte os seguintes recursos na documentação do Visual Studio:

Usar Visual Studio Code para desenvolvimento multiplataforma Blazor

O Visual Studio Code é um IDE (Ambiente de Desenvolvimento Integrado) de código aberto e multiplataforma que pode ser usado para desenvolver aplicativos Blazor. Use a CLI do .NET para criar um novo aplicativo Blazor para desenvolvimento com o Visual Studio Code. Para obter mais informações, consulte a versão do Linux/macOS deste artigo.

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

Opções de modelo Blazor

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 Aplicativo Web Blazor: 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.

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:
  • 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
  • Os Modelos padrão do .NET para o novo artigo do dotnet na documentação do .NET Core:
  • 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
  • Os Modelos padrão do .NET para o novo artigo do dotnet na documentação do .NET Core:
  • 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

Recursos adicionais