共用方式為

使用指導

  • 發行項

Microsoft.AspNetCore.SystemWebAdapters 提供一個模擬層，模擬 ASP.NET Core 上 ASP.NET Framework 的行為。 以下是使用時一些考慮的指導方針:

HttpContext 存留期

配接器會受到 HttpContext 的支援，因此無法在要求的存留期之後使用。 因此，HttpContext 當在 ASP.NET Core 上執行時，也無法在要求之後使用，而在 ASP.NET Framework 上則有時會運作。 ObjectDisposedException 在要求結束之前使用時，將會擲回。

建議: 將所需的值儲存到 POCO 中，並保留至該值。

轉換至 HttpContext

有兩種方式可將 HttpContext 轉換成 HttpContext:

  • 隱含轉換
  • 建構函式使用方式

建議: 在大部分情況下，應該優先使用隱含轉換，因為這樣會快取建立的執行個體，並確保每個要求只有一個 HttpContext。

預設不會設定 CurrentCulture

在 ASP.NET Framework 中， CurrentCulture 已針對要求設定，但這不會在 ASP.NET Core 中自動完成。 相反地，您必須將適當的中介軟體新增至管線。

建議: 如需如何啟用這項功能的詳細資訊，請參閱 ASP.NET Core當地語系化。

使用與 ASP.NET Framework 類似的行為來啟用這項功能最簡單的方式，就是將下列內容新增至管線:

app.UseRequestLocalization();

CurrentPrincipal

在 ASP.NET Framework 中，CurrentPrincipal 和 Current 會設定為目前的使用者。 這在 ASP.NET Core 上無法即刻開箱即用。 藉由將 ISetThreadCurrentPrincipal 新增至端點 (可透過 SetThreadCurrentPrincipalAttribute 讓控制器使用)，即可透過這些配接器取得支援。 不過，只有在無法重構程式碼以移除使用方式時，才應該使用它。

建議: 可能的話，請使用屬性 User 或 User 而不是將屬性傳遞至呼叫網站。 如果不可能，啟用設定目前的使用者，並考慮將要求設定為邏輯單一執行緒 (請參閱下方以取得詳細資料)。

ASP.NET Core 中不存在要求執行緒

在 ASP.NET Framework 中，要求具有執行緒親和性，且 Current 只能在該執行緒上使用。 ASP.NET Core 沒有這項保證，因此 Current 可以在相同的非同步內容中使用，但不會保證執行緒。

建議: 如果讀取/寫入至 HttpContext ，您必須確保以單一執行緒的方式執行此動作。 藉由設定 ISingleThreadedRequestMetadata，您可以強制要求永遠不要在任何非同步內容上同時執行。 這會產生效能影響，只有在您無法重構使用方式以確保非平行存取時，才應該使用。 有一個實作可供使用以降 SingleThreadedRequestAttribute 新增至控制器:

[SingleThreadedRequest]
public class SomeController : Controller
{
    ...
}

Request 可能需要預先緩衝

根據預設，傳入要求不一定是可搜尋的，也不完全可用。 若要取得在 .NET Framework 中看到的行為，您可以選擇預先緩衝輸入資料流。 這會完整讀取傳入的資料流，並將它緩衝至記憶體或磁蝶 (視設定而定)。

建議: 您可以套用實作 IPreBufferRequestStreamMetadata 介面的端點中繼資料來啟用此功能。 這可作為可套用至控制器或方法的屬性 PreBufferRequestStreamAttribute。

若要在所有 MVC 端點上啟用此功能，有一個擴充方法可用，如下所示:

app.MapDefaultControllerRoute()
    .PreBufferRequestStream();

Response 可能需要緩衝處理

Response 上的某些 API 需要緩衝輸出資料流，例如 Output、End()、Clear() 和 SuppressContent。

建議: 為了支援在傳送之前需要緩衝回應的行為 Response，端點必須使用端點中繼資料實作 IBufferResponseStreamMetadata 來選擇加入它。

若要在所有 MVC 端點上啟用此功能，有一個擴充方法可用，如下所示:

app.MapDefaultControllerRoute()
    .BufferResponseStream();

共用的工作階段狀態

為了支援 Session，端點必須透過中繼資料實作 ISessionMetadata 來選擇加入它。

建議: 若要在所有 MVC 端點上啟用此功能，有一個擴充方法可以使用，如下所示:

app.MapDefaultControllerRoute()
    .RequireSystemWebAdapterSession();

這也需要工作階段存放區的一些實作。 如需這裡的選項詳細資料，請參閱 [這裡]。

遠端工作階段會公開應用程式的其他端點

遠端工作階段支援 會公開端點，讓核心應用程式擷取工作階段資訊。 這可能會導致核心應用程式與架構應用程式之間有長時間存在的要求，但會因目前的要求或工作階段逾時而逾時 (預設為 20 分鐘)。

建議: 請確定使用的 API 金鑰是強式金鑰，且與架構應用程式的連線是透過 SSL 完成的。

架構和核心應用程式的虛擬目錄必須相同

虛擬目錄設定用於系統內的路由產生、授權和其他服務。 此時，由於 ASP.NET Framework 的運作方式，找不到可啟用不同虛擬目錄的可靠方法。

建議：請確定兩個應用程式皆位於具有相同應用程式/虛擬目錄配置的不同網站 (主機和/或連接埠)。