# Getting Started

## Storage

Hangfire 會將所有相關資訊會被序列化後保存到儲存區，如類型、方法或參數等。

儲存模型官方預設有以下幾種

<table>
    <thead>
        <td></td>
        <td>Sql Server 2008+</td>
        <td>Redis 2.6.12+</td>
        <td>In-Memory</td>
        <td>Price</td>
    </thead>
    <tbody>
        <td>Open</td>
        <td>✔</td>
        <td></td>
        <td>✔</td>
        <td>free</td>
    </tbody>
    <tbody>
        <td>Startup</td>
        <td>✔</td>
        <td>✔</td>
        <td>✔</td>
        <td>$500 / per year</td>
    </tbody>
    <tbody>
        <td>Business</td>
        <td>✔</td>
        <td>✔</td>
        <td>✔</td>
        <td>$1,500 / per year</td>
    </tbody>
    <tbody>
        <td>Enterprise</td>
        <td>✔</td>
        <td>✔</td>
        <td>✔</td>
        <td>$4,500 / per year</td>
    </tbody>
</table>

資料來源日期: 2024/03/12

```C#
// Hangfire 1.8
GlobalConfiguration
    .Configuration
    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
    .UseSimpleAssemblyNameTypeSerializer()
    .UseRecommendedSerializerSettings()
    .UseSqlServerStorage("Database=Hangfire.Sample; Integrated Security=True;");

// Hangfire 1.7
GlobalConfiguration
    .Configuration
    .SetDataCompatibilityLevel(CompatibilityLevel.Version_170)
    .UseSimpleAssemblyNameTypeSerializer()
    .UseRecommendedSerializerSettings()
    .UseSqlServerStorage("Database=Hangfire.Sample; Integrated Security=True;", new SqlServerStorageOptions
    {
        CommandBatchMaxTimeout = TimeSpan.FromMinutes(5),
        SlidingInvisibilityTimeout = TimeSpan.FromMinutes(5),
        QueuePollInterval = TimeSpan.Zero,
        UseRecommendedIsolationLevel = true,
        DisableGlobalLocks = true, // Migration to Schema 7 is required
    });

// Hangfire SQLite
GlobalConfiguration
    .Configuration
    .UseSQLiteStorage("HangfireExample.db"));
```

## Server

啟動 Hangfire 伺服器

```C#
services.AddHangfireServer();
```

## Using Dashboard UI

開啟 Dashboard 功能

```C#
app.UseHangfireDashboard();
```

* Configuring Authorization

設定自定義驗證

```C#
app.UseHangfireDashboard("hangfire", new DashboardOptions
{
    Authorization = [new DashboardAuthorizationFilter()],
});
```

* Read-only view

設定 UI 為 ReadOnly

```C#
app.UseHangfireDashboard("hangfire", new DashboardOptions
{
    IsReadOnlyFunc = (DashboardContext context) => true,
});
```

* Change URL Mapping

修改 Dashboard UI 的預設根路由

```C#
app.UseHangfireDashboard("hangfire");
```

* Change Back to site Link

修改返回按鈕的路由

```C#
app.UseHangfireDashboard("hangfire", new DashboardOptions
{
    AppPath = "/swagger", // 導向到 Swagger UI
});
```

![BackToSite](HangfireResources/BackToSite.jpg)

* Multiple Dashboards

設定不同資料來源的 Dashboard

```C#
app.UseHangfireDashboard(configuration.GetValue<string>("DashboardRoot"), new DashboardOptions
{
    Authorization = [new DashboardAuthorizationFilter()],
    // 指定 Dashboard 指定讀取，不能操作，如重新執行、再次加入排程與刪除任務等
    IsReadOnlyFunc = (DashboardContext context) => true,
    // 指定 Back to site 的連結
    AppPath = "/swagger",
}, new SQLiteStorage("HangfireExample2.db"));
```

## Background Methods

排程可以直接執行特定方法，Hangfire 會將方法(可使用非同步)、類型與參數序列化後保存到資料庫，Hangfire 依照排程類型，分為以下四種

* Fire-and-Forget jobs: 將任務丟入執行佇列，直接執行

```C#
BackgroundJob.Enqueue(() => Console.WriteLine("Fire-and-Forget"));
```

* Delayed jobs: 延遲指定時間後，將任務丟入執行佇列

```C#
BackgroundJob.Schedule(() => Console.WriteLine("Delayed"), TimeSpan.FromDays(1));
```

* Recurring jobs: 依照指定間隔，將任務丟入執行佇列

Cron Expression [測試](https://crontab.guru/)

<table>
    <thead>
        <td>分</td>
        <td>時</td>
        <td>月中的日</td>
        <td>月</td>
        <td>週中的日</td>
        <td>說明</td>
    </thead>
    <tbody>
        <tr>
            <td>0/30</td>
            <td>*</td>
            <td>*</td>
            <td>*</td>
            <td>*</td>
            <td>每30分鐘執行一次</td>
        </tr>
        <tr>
            <td>30</td>
            <td>9</td>
            <td>*</td>
            <td>*</td>
            <td>*</td>
            <td>每日早上09:30執行一次(UTC)</td>
        </tr>
        <tr>
            <td>30</td>
            <td>9</td>
            <td>*</td>
            <td>*</td>
            <td>MON-FRI</td>
            <td>每週一到週五早上09:30執行一次(UTC)</td>
        </tr>
        <tr>
            <td>30</td>
            <td>09</td>
            <td>1</td>
            <td>*</td>
            <td>*</td>
            <td>每月1號早上09:30執行一次(UTC)</td>
        </tr>
        <tr>
            <td>0-30/30</td>
            <td>9</td>
            <td>*</td>
            <td>*</td>
            <td>*</td>
            <td>每日早上09:00~09:30，每30分鐘執行一次(UTC)</td>
        </tr>
        <tr>
            <td>0/30</td>
            <td>9-12</td>
            <td>*</td>
            <td>*</td>
            <td>*</td>
            <td>每日早上09:00~12:00，每30分鐘執行一次(UTC)</td>
        </tr>
        <tr>
            <td>0/30</td>
            <td>9-12</td>
            <td>1-5</td>
            <td>*</td>
            <td>*</td>
            <td>每月1號到5號早上09:00~12:00，每30分鐘執行一次(UTC)</td>
        </tr>
    </tbody>
</table>

```C#
RecurringJob.AddOrUpdate("job_id", () => Console.Write("Recurring By CRON"), Cron.Daily);

RecurringJob.AddOrUpdate("job_id", () => Console.Write("Recurring By CRON expressions"), "* 0/1 * * ? *");
```

移除已存在的排程任務

```C#
RecurringJob.RemoveIfExists("job_id");
```

手動觸發已存在的排程任務

```C#
RecurringJob.Trigger("job_id");
```


* Continuations: 指定的任務完成後，才丟入執行佇列

```C#
var jobId = BackgroundJob.Enqueue(() => Console.WriteLine("Fire-and-Forget"));

BackgroundJob.ContinueJobWith(jobid, () => Console.WriteLine("Continuations"));
```

## Extensions

### Progressing text console and show bar

使用 IPerformContextAccessor 從 Hangfire 的 PerformContext 取得進度管理的元件後，透過 Console 提供的擴充輸出到 GUI 管理介面。

```shell
NUGET INSTALL Bonura.Hangfire.PerformContextAccessor -Version 1.3.3

NUGET INSTALL Hangfire.Console -Version 1.4.3
```

![ProgressBar](HangfireResources/ProgressBar.jpg)

Console 套件同時也提供格式化輸出字串的功能。

```C#
// 取得 Hangfire 的進程管理
var bar = context.WriteProgressBar();

context.WriteLine("The text color change to red");

context.SetTextColor(ConsoleTextColor.Red);

context.WriteLine("This progress is ready to start");

context.ResetTextColor();

// 使用 WithProgress 方法回報進程管理，任務的進度已更新
foreach (var i in Enumerable.Range(0, seconds).ToList().WithProgress(bar))
{
    Thread.Sleep(1000);
}

context.SetTextColor(ConsoleTextColor.Green);

context.WriteLine("This progress has finished");

context.ResetTextColor();
```