Skip to main content

2.0 入门指南

版本说明

以下内容仅限 Furion 3.6.3 + 版本使用。

推荐使用脚手架

Furion 官方提供了非常灵活方便的脚手架，可以快速的创建多层架构项目。

推荐使用 《2.2 官方脚手架》代替本章节功能。

2.0.1 历史背景​

相信从 ASP.NET 5 升级至 ASP.NET 6 的开发者都经历过这样变更：

  • 在 ASP.NET 5 中，我们这样创建 Web 主机：
Program.cs
Host.CreateDefaultBuilder(args)    .ConfigureWebHostDefaults(webBuilder =>    {        webBuilder.UseStartup<Startup>();    });
  • 在 ASP.NET 6 中， 我们这样创建 Web 主机：
Program.cs
var builder = WebApplication.CreateBuilder(args);var app = builder.Build();

试问，ASP.NET 7，ASP.NET 8 ... ASP.NET N 呢？会不会每一个版本都有不同的创建方式，那后续项目如何无缝升级？

所以，为了保证一致的代码体验和后续无缝升级，创造出了 Serve.Run()，即使未来创建方式变了，也不用担心，交给框架即可。

2.0.2 创建 控制台 项目​

  • 打开 Visual Studio 2022 并创建 控制台 项目
  • 配置项目名称
  • 选择 .NET6
使用命令行方式
// 创建控制台项目dotnet new console -n HelloFurion

2.0.3 添加 Furion 依赖包​

使用命令行方式
// 进入创建的目录cd HelloFurion// 添加包dotnet add package Furion

2.0.4 一句话搞定​

修改 Program.cs 代码为：

Program.cs
Serve.Run();

对，你没看错，Furion 已经配置好了！

2.0.5 启动浏览器​

启动浏览器查看效果

是不是超级超级简单！！！

2.0.6 编写第一个 API​

Program.cs
Serve.Run();[DynamicApiController]public class HelloService{    public string Say()    {        return "Hello, Furion";    }}

启动浏览器查看效果

2.0.7 Serve.Run() 更多配置​

2.0.7.1 配置默认端口​

默认情况下，创建的 Web 主机端口为 5000/5001 端口，如需自定义配置，可通过第一个参数配置：

Serve.Run("https://localhost:8080");

同时也支持 dotnet run 和 dotnet watch run 指定：

dotnet run --urls https://localhost:8080# watch 方式dotnet watch run --urls https://localhost:8080

也可以通过 ConfigureBuilder 方式配置：

Serve.Run(RunOptions.Default.ConfigureBuilder(builder =>{    builder.WebHost.UseUrls("https://localhost:8080");  // 也可以通过 builder.Configuration 读取 urls 配置}));
关于 localhost 和多端口

建议使用 * 代替 localhost，这样可以自适应主机地址，多个端口使用 ; 分割，结尾无需 ;

通过 json 方式配置

如需通过配置文件配置端口，需两个该步骤：

  1. 编辑控制台启动项目 .csproj 文件，修改 Project 节点为：
<Project Sdk="Microsoft.NET.Sdk.Web">

也就是在原来的 Sdk 中添加 .Web 即可。

  1. 在控制台启动项目中添加 Properties 文件夹并在此文件夹中创建 launchSettings.json 文件，同时写入以下内容：
{  "$schema": "http://json.schemastore.org/launchsettings.json",  "profiles": {    "启动项目名称": {      "commandName": "Project",      "launchBrowser": true,      "launchUrl": "",      "applicationUrl": "https://localhost:8080;http://localhost:8081",      "environmentVariables": {        "ASPNETCORE_ENVIRONMENT": "Development"      }    }  }}

2.0.7.2 自定义配置​

传入 RunOptions 对象相当于自由定义和控制，也就是除了默认集成了 Furion 以外，没有注册任何功能。

  • 仅集成 Furion 的默认配置
Serve.Run(RunOptions.Default);
  • 配置更多服务/中间件
Serve.Run(RunOptions.Default    .ConfigureBuilder(builder =>    {        builder.Services.AddControllers()                        .AddInject();    })    .Configure(app =>    {        app.UseRouting();        app.UseInject(string.Empty);        app.UseEndpoints(endpoints =>        {            endpoints.MapControllers();        });    }));

2.0.7.3 Serve.Run 和 Startup 最佳组合​

默认情况下 Serve.Run() 内置了 跨域，控制器，路由，规范化结果、静态文件 服务/中间件。适合快速开始项目和编写测试代码。

但不能对这些已注册服务/中间件进行自定义配置，这时只需要配置 RunOptions 属性/方法即可，如：

Program.cs
Serve.Run(RunOptions.Default    .ConfigureBuilder(...)    .Configure(..));

但把所有服务/中间件都放在 Program.cs 中好吗？答案是不好的，因为会导致后续迁移代码维护代码造成了一些困扰。

所以 Furion 推荐下面更加灵活且易维护的方式，Program.cs 只需一句话即可：

Program.cs
Serve.Run(RunOptions.Default);

然后添加自定义 Startup.cs 文件，代码如下：

Startup.cs
using Furion;using Microsoft.AspNetCore.Builder;using Microsoft.AspNetCore.Hosting;using Microsoft.Extensions.DependencyInjection;namespace HelloFurion;public class Startup : AppStartup{    public void ConfigureServices(IServiceCollection services)    {        // ....    }    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)    {        // ....    }}
小提示

正常情况下，自定义 Startup.cs 文件应该放在独立的 YourProject.Web.Core 层或其他层。

2.0.7.4 更多配置​

如配置 WebHost...

Serve.Run(RunOptions.Default    .ConfigureBuilder(builder => {        builder.WebHost.....    }));

2.0.8 支持 Furion 所有功能​

Serve.Run() 看似非常简单，实则非常灵活，而且支持 Furion 和 .NET 所有功能。

2.0.8.1 添加 appsettings.json​

创建 appsettings.json 文件，并设置 属性 为 如果较新则复制 和 内容（生成操作）

{  "Logging": {    "LogLevel": {      "Default": "Information",      "Microsoft": "Warning",      "Microsoft.Hosting.Lifetime": "Information",      "Microsoft.EntityFrameworkCore": "Information"    }  },  "AllowedHosts": "*"}

在代码中读取配置：

using Furion;Serve.Run();[DynamicApiController]public class HelloService{    public string Say()    {        return "Hello, Furion " + App.Configuration["Logging:LogLevel:Default"];    }}

2.0.8.2 添加自定义 Startup​

在 Furion 中可以派生自 AppStartup 可以实现更多配置，如：

Program.cs
Serve.Run();
MyStartup.cs
using Furion;using Microsoft.AspNetCore.Builder;using Microsoft.AspNetCore.Hosting;using Microsoft.Extensions.DependencyInjection;namespace HelloFurion;public class MyStartup : AppStartup{    public void ConfigureServices(IServiceCollection services)    {        Console.WriteLine("调用服务注册啦~~");    }    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)    {        Console.WriteLine("调用中间件注册啦");    }}

2.0.8.3 将控制台项目变成 Web 项目​

只需要编辑 .csproj 文件，将第一行 Project 节点的 Sdk

<Project Sdk="Microsoft.NET.Sdk">

修改为：

<Project Sdk="Microsoft.NET.Sdk.Web">

即可完成转换，实际上只是追加了 .Web。

2.0.8.4 还没看够？​

是不是非常强大啊，Serve.Run() 虽然简单，但是 100% 支持 Furion 和 .NET 所有功能。尽情去体验吧！

2.0.9 RunOptions，LegacyRunOptions 和 GenericRunOptions​

Serve.Run 提供了 RunOptions，LegacyRunOptions 和 GenericRunOptions 重载参数类型，他们的主要区别：

  • RunOptions：使用的是 WebApplication 方式，创建 Web 主机优先推荐方式
  • LegacyRunOptions：使用的是 Host 方式，但默认配置了 Web 主机
  • GenericRunOptions：使用的是 Host 方式，通用类型主机，可用于 WorkerService

LegacyRunOptions 配置例子：

using Microsoft.AspNetCore.Hosting;using Microsoft.Extensions.DependencyInjection;Serve.Run(LegacyRunOptions.Default    // 配置 Web 主机    .ConfigureWebDefaults(builder =>    {        builder.ConfigureServices(services =>        {            // ...        })        .Configure(app =>        {            // ...        });    })    // 配置 Host 主机    .ConfigureBuilder(builder =>    {        // ...    }));

GenericRunOptions 配置例子：

Serve.Run(GenericRunOptions.Default    // 配置 Host 主机    .ConfigureBuilder(hostBuilder =>    {       // ...    }));

2.0.10 如何发布​

由于是控制台应用程序，我们直接将 Visual Studio 切换成 Release 编译即可~~。

也可以通过下列命令发布：

dotnet publish -c Release

更多发布命令说明可查阅微软官方文档 https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish

2.0.11 反馈与建议​

与我们交流

给 Furion 提 Issue。

演练场