Usar o modelo de projeto Angular com o ASP.NET CoreUse the Angular project template with ASP.NET Core

O modelo de projeto do Angular atualizado fornece um ponto inicial conveniente para aplicativos do ASP.NET Core usando o Angular e a CLI do Angular para implementar uma IU (interface do usuário) avançada do lado do cliente.The updated Angular project template provides a convenient starting point for ASP.NET Core apps using Angular and the Angular CLI to implement a rich, client-side user interface (UI).

O modelo é equivalente à criação de um projeto do ASP.NET Core para atuar como um back-end de API e um projeto de CLI do Angular para atuar como uma interface do usuário.The template is equivalent to creating an ASP.NET Core project to act as an API backend and an Angular CLI project to act as a UI. O modelo oferece a conveniência de hospedagem de ambos os tipos de projeto em um projeto de aplicativo único.The template offers the convenience of hosting both project types in a single app project. Consequentemente, o projeto de aplicativo pode ser criado e publicado como uma única unidade.Consequently, the app project can be built and published as a single unit.

Criar um novo aplicativoCreate a new app

Se você tiver o ASP.NET Core 2.1 instalado, não será necessário instalar o modelo de projeto Angular.If you have ASP.NET Core 2.1 installed, there's no need to install the Angular project template.

Crie um novo projeto de um prompt de comando usando o comando dotnet new angular em um diretório vazio.Create a new project from a command prompt using the command dotnet new angular in an empty directory. Por exemplo, os seguintes comandos criam o aplicativo em um diretório my-new-app e mudam para esse diretório:For example, the following commands create the app in a my-new-app directory and switch to that directory:

dotnet new angular -o my-new-app
cd my-new-app

Execute o aplicativo do Visual Studio ou da CLI do .NET Core:Run the app from either Visual Studio or the .NET Core CLI:

Abra o arquivo .csproj gerado e execute o aplicativo normalmente de lá.Open the generated .csproj file, and run the app as normal from there.

O processo de build restaura dependências npm na primeira execução, o que pode levar vários minutos.The build process restores npm dependencies on the first run, which can take several minutes. Builds subsequentes são muito mais rápidos.Subsequent builds are much faster.

O modelo de projeto cria um aplicativo ASP.NET Core e um aplicativo do Angular.The project template creates an ASP.NET Core app and an Angular app. O aplicativo ASP.NET Core destina-se a ser usado para acesso a dados, autorização e outras questões do lado do servidor.The ASP.NET Core app is intended to be used for data access, authorization, and other server-side concerns. O aplicativo do Angular, que reside no subdiretório ClientApp, destina-se a ser usado para todas as questões de interface do usuário.The Angular app, residing in the ClientApp subdirectory, is intended to be used for all UI concerns.

Adicione páginas, imagens, estilos, módulos, etc.Add pages, images, styles, modules, etc.

O diretório ClientApp contém um aplicativo padrão da CLI do Angular.The ClientApp directory contains a standard Angular CLI app. Veja a documentação oficial do Angular para obter mais informações.See the official Angular documentation for more information.

Há pequenas diferenças entre o aplicativo do Angular criado por este modelo e um criado pela CLI do Angular propriamente dita (por meio de ng new); no entanto, os recursos do aplicativo são inalterados.There are slight differences between the Angular app created by this template and the one created by Angular CLI itself (via ng new); however, the app's capabilities are unchanged. O aplicativo criado pelo modelo contém um layout com base em Bootstrap e um exemplo básico de roteamento.The app created by the template contains a Bootstrap-based layout and a basic routing example.

Executar comandos ngRun ng commands

Em um prompt de comando, mude para o subdiretório ClientApp:In a command prompt, switch to the ClientApp subdirectory:

cd ClientApp

Se você tiver a ferramenta ng instalada globalmente, você poderá executar qualquer um dos seus comandos.If you have the ng tool installed globally, you can run any of its commands. Por exemplo, você poderá executar ng lint, ng test ou qualquer um dos outros comandos da CLI do Angular.For example, you can run ng lint, ng test, or any of the other Angular CLI commands. No entanto, não é necessário executar ng serve, porque o seu aplicativo ASP.NET Core dá conta de servir tanto a parte do lado do servidor quanto a do lado do cliente do seu aplicativo.There's no need to run ng serve though, because your ASP.NET Core app deals with serving both server-side and client-side parts of your app. Internamente, ele usa ng serve em desenvolvimento.Internally, it uses ng serve in development.

Se você não tiver a ferramenta ng instalada, execute npm run ng em vez dela.If you don't have the ng tool installed, run npm run ng instead. Por exemplo, você pode executar npm run ng lint ou npm run ng test.For example, you can run npm run ng lint or npm run ng test.

Instalar pacotes npmInstall npm packages

Para instalar pacotes npm de terceiros, use um prompt de comando no subdiretório ClientApp.To install third-party npm packages, use a command prompt in the ClientApp subdirectory. Por exemplo:For example:

cd ClientApp
npm install --save <package_name>

Publicar e implantarPublish and deploy

No desenvolvimento, o aplicativo é executado de um modo otimizado para conveniência do desenvolvedor.In development, the app runs in a mode optimized for developer convenience. Por exemplo, pacotes JavaScript incluem mapas de origem (de modo que durante a depuração, você pode ver o código TypeScript original).For example, JavaScript bundles include source maps (so that when debugging, you can see your original TypeScript code). O aplicativo observa alterações em arquivos TypeScript, HTML e CSS no disco e recompila e recarrega automaticamente quando as detecta.The app watches for TypeScript, HTML, and CSS file changes on disk and automatically recompiles and reloads when it sees those files change.

Em produção, atende a uma versão de seu aplicativo que é otimizada para desempenho.In production, serve a version of your app that's optimized for performance. Isso é configurado para ocorrer automaticamente.This is configured to happen automatically. Quando você publica, a configuração de build emite um build minificado em compilação AoT (Ahead Of Time) do código do lado do cliente.When you publish, the build configuration emits a minified, ahead-of-time (AoT) compiled build of your client-side code. Diferentemente da compilação de desenvolvimento, o build de produção não exige o Node. js para ser instalado no servidor (a menos que você habilitou a renderização do lado do servidor (SSR)).Unlike the development build, the production build doesn't require Node.js to be installed on the server (unless you have enabled server-side rendering (SSR)).

Você pode usar os métodos padrão de implantação e hospedagem do ASP.NET Core.You can use standard ASP.NET Core hosting and deployment methods.

Executar "ng serve" independentementeRun "ng serve" independently

O projeto está configurado para iniciar sua própria instância do servidor da CLI do Angular em segundo plano quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento.The project is configured to start its own instance of the Angular CLI server in the background when the ASP.NET Core app starts in development mode. Isso é conveniente, porque você não precisa executar um servidor separado manualmente.This is convenient because you don't have to run a separate server manually.

Há uma desvantagem nessa configuração padrão.There's a drawback to this default setup. Cada vez que você modificar seu código C# e o aplicativo ASP.NET Core precisar ser reiniciado, o servidor da CLI do Angular será reiniciado também.Each time you modify your C# code and your ASP.NET Core app needs to restart, the Angular CLI server restarts. São necessários aproximadamente 10 segundos para iniciar um backup.Around 10 seconds is required to start back up. Se você estiver fazendo edições frequentes de código C# e não quiser esperar a CLI do Angular reiniciar, execute o servidor da CLI do Angular externamente, independentemente do processo do ASP.NET Core.If you're making frequent C# code edits and don't want to wait for Angular CLI to restart, run the Angular CLI server externally, independently of the ASP.NET Core process. Para fazer isso:To do so:

  1. Em um prompt de comando, vá para o subdiretório ClientApp e inicie o Development Server da CLI do Angular:In a command prompt, switch to the ClientApp subdirectory, and launch the Angular CLI development server:

    cd ClientApp
    npm start
    

    Importante

    Use npm start para iniciar o Development Server da CLI do Angular, não ng serve, de modo que a configuração no package.json seja respeitada.Use npm start to launch the Angular CLI development server, not ng serve, so that the configuration in package.json is respected. Para passar parâmetros adicionais para o servidor da CLI do Angular, adicione-os à linha scripts relevante em seu arquivo package.json.To pass additional parameters to the Angular CLI server, add them to the relevant scripts line in your package.json file.

  2. Modifique o aplicativo ASP.NET Core para, em vez de iniciar uma instância da CLI do Angular própria, usar a externa.Modify your ASP.NET Core app to use the external Angular CLI instance instead of launching one of its own. Na classe Startup, substitua a invocação spa.UseAngularCliServer pelo seguinte:In your Startup class, replace the spa.UseAngularCliServer invocation with the following:

    spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");
    

Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor da CLI do Angular.When you start your ASP.NET Core app, it won't launch an Angular CLI server. Em vez disso, a instância que você iniciou manualmente é usada.The instance you started manually is used instead. Isso permite a ele iniciar e reiniciar mais rapidamente.This enables it to start and restart faster. Ele não está mais aguardando a CLI do Angular recompilar o aplicativo cliente a cada vez.It's no longer waiting for Angular CLI to rebuild your client app each time.

Passar dados de código .NET para código do TypeScriptPass data from .NET code into TypeScript code

Durante a SSR, convém passar dados por solicitação, do aplicativo ASP.NET Core para o aplicativo do Angular.During SSR, you might want to pass per-request data from your ASP.NET Core app into your Angular app. Por exemplo, você pode transmitir informações de cookie ou algo lido de um banco de dados.For example, you could pass cookie information or something read from a database. Para fazer isso, edite a classe Startup.To do this, edit your Startup class. No retorno de chamada para UseSpaPrerendering, defina um valor para options.SupplyData como o seguinte:In the callback for UseSpaPrerendering, set a value for options.SupplyData such as the following:

options.SupplyData = (context, data) =>
{
    // Creates a new value called isHttpsRequest that's passed to TypeScript code
    data["isHttpsRequest"] = context.Request.IsHttps;
};

O retorno de chamada SupplyData permite que você passe dados serializáveis por JSON arbitrários e por solicitação (por exemplo, cadeias de caracteres, boolianos ou números).The SupplyData callback lets you pass arbitrary, per-request, JSON-serializable data (for example, strings, booleans, or numbers). O código de main.server.ts recebe isso como params.data.Your main.server.ts code receives this as params.data. Por exemplo, o exemplo de código anterior passa um valor booliano como params.data.isHttpsRequest para o retorno de chamada createServerRenderer.For example, the preceding code sample passes a boolean value as params.data.isHttpsRequest into the createServerRenderer callback. Você pode passar isso para outras partes do seu aplicativo de alguma forma compatível com o Angular.You can pass this to other parts of your app in any way supported by Angular. Por exemplo, veja como main.server.ts passa o valor BASE_URL para qualquer componente cujo construtor é declarado para recebê-lo.For example, see how main.server.ts passes the BASE_URL value to any component whose constructor is declared to receive it.

Desvantagens da SSRDrawbacks of SSR

Nem todos os aplicativos se beneficiam da SSR.Not all apps benefit from SSR. O principal benefício é o desempenho percebido.The primary benefit is perceived performance. Os visitantes que chegam ao aplicativo por uma conexão de rede lenta ou em dispositivos móveis lentos veem a interface do usuário inicial rapidamente, mesmo que leve algum tempo para buscar ou para analisar os pacotes de JavaScript.Visitors reaching your app over a slow network connection or on slow mobile devices see the initial UI quickly, even if it takes a while to fetch or parse the JavaScript bundles. No entanto, muitos SPAs são usados principalmente em redes de empresa internas e rápidas, em computadores rápidos nos quais o aplicativo aparece quase instantaneamente.However, many SPAs are mainly used over fast, internal company networks on fast computers where the app appears almost instantly.

Ao mesmo tempo, há desvantagens significativas em habilitar a SSR.At the same time, there are significant drawbacks to enabling SSR. Ele adiciona complexidade ao seu processo de desenvolvimento.It adds complexity to your development process. O código deve ser executado em dois ambientes diferentes: no lado do cliente e no do servidor (em um ambiente Node.js invocado do ASP.NET Core).Your code must run in two different environments: client-side and server-side (in a Node.js environment invoked from ASP.NET Core). Estes são alguns pontos a considerar:Here are some things to bear in mind:

  • A SSR requer uma instalação de Node.js nos servidores de produção.SSR requires a Node.js installation on your production servers. Isso ocorre automaticamente para alguns cenários de implantação como Serviços de Aplicativos do Azure, mas não para outros como o Azure Service Fabric.This is automatically the case for some deployment scenarios, such as Azure App Services, but not for others, such as Azure Service Fabric.

  • Habilitar o sinalizador de build BuildServerSideRenderer faz com que o diretório node_modules seja publicado.Enabling the BuildServerSideRenderer build flag causes your node_modules directory to publish. Esta pasta contém mais de 20.000 arquivos, o que aumenta o tempo de implantação.This folder contains 20,000+ files, which increases deployment time.

  • Para executar o código em um ambiente Node.js, ele não pode depender da existência de APIs de JavaScript específicas a um navegador, tais como window ou localStorage.To run your code in a Node.js environment, it can't rely on the existence of browser-specific JavaScript APIs such as window or localStorage. Se seu código (ou alguma biblioteca de terceiros à qual você faz referência) tentar usar essas APIs, você obterá um erro durante a SSR.If your code (or some third-party library you reference) tries to use these APIs, you'll get an error during SSR. Por exemplo, não use jQuery porque faz referência a APIs específicas a um navegador em vários locais.For example, don't use jQuery because it references browser-specific APIs in many places. Para evitar erros, você deve evitar a SSR ou então evitar APIs ou bibliotecas específicas a um navegador.To prevent errors, you must either avoid SSR or avoid browser-specific APIs or libraries. Você pode encapsular todas as chamadas para essas APIs em verificações para garantir que elas não sejam invocadas durante a SSR.You can wrap any calls to such APIs in checks to ensure they aren't invoked during SSR. Por exemplo, use uma verificação como a seguinte no código JavaScript ou TypeScript:For example, use a check such as the following in JavaScript or TypeScript code:

    if (typeof window !== 'undefined') {
        // Call browser-specific APIs here
    }
    

Recursos adicionaisAdditional resources