/// <summary>
/// Registers a <see cref="Frame"/> instance to allow its navigation history to be saved to
/// and restored from <see cref="SessionState"/>. Frames should be registered once
/// immediately after creation if they will participate in session state management. Upon
/// registration if state has already been restored for the specified key
/// the navigation history will immediately be restored. Subsequent invocations of
/// <see cref="RestoreAsync"/> will also restore navigation history.
/// </summary>
/// <param name="frame">An instance whose navigation history should be managed by
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">A unique key into <see cref="SessionState"/> used to
/// store navigation-related information.</param>
/// <param name="sessionBaseKey">An optional key that identifies the type of session.
/// This can be used to distinguish between multiple application launch scenarios.</param>
public static void RegisterFrame(Frame frame, String sessionStateKey, String sessionBaseKey = null)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
if (!string.IsNullOrEmpty(sessionBaseKey))
{
frame.SetValue(FrameSessionBaseKeyProperty, sessionBaseKey);
sessionStateKey = sessionBaseKey + "_" + sessionStateKey;
}
// Use a dependency property to associate the session key with a frame, and keep a list of frames whose
// navigation state should be managed
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// Check to see if navigation state can be restored
RestoreFrameNavigationState(frame);
}
/// <summary>
/// Provides storage for session state associated with the specified <see cref="Frame"/>.
/// Frames that have been previously registered with RegisterFrame have
/// their session state saved and restored automatically as a part of the global
/// SessionState. Frames that are not registered have transient state
/// that can still be useful when restoring pages that have been discarded from the
/// navigation cache.
/// </summary>
/// <remarks>Apps may choose to rely on <see cref="LayoutAwarePage"/> to manage
/// page-specific state instead of working with frame session state directly.</remarks>
/// <param name="frame">The instance for which session state is desired.</param>
/// <returns>A collection of state subject to the same serialization mechanism as
/// SessionState.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// Registered frames reflect the corresponding session state
if (!SessionState.ContainsKey(frameSessionKey))
{
SessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)SessionState[frameSessionKey];
}
else
{
// Frames that aren't registered have transient state
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
public static void RegisterFrame(Frame frame, string sessionStateKey, string sessionBaseKey = null)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registerd before accessing frame session staet, or not registered at all");
}
if (!string.IsNullOrEmpty(sessionBaseKey))
{
frame.SetValue(FrameSessionBaseKeyProperty, sessionBaseKey);
sessionStateKey = sessionStateKey + "_" + sessionStateKey;
}
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
RestoreFrameNavigationState(frame);
}
/// <summary>
/// Hebt die Verknüpfung eines <see cref="Frame"/>, der zuvor durch <see cref="RegisterFrame"/> registriert wurde,
/// mit <see cref="SessionState"/> auf. Alle zuvor erfassten Navigationszustände werden
/// entfernt.
/// </summary>
/// <param name="frame">Eine Instanz, deren Navigationsverlauf nicht mehr
/// verwaltet werden soll.</param>
public static void UnregisterFrame(Frame frame)
{
// Sitzungszustand und Rahmen aus der Liste der Rahmen entfernen, deren Navigationszustand
// gespeichert wird (gemeinsam mit allen schwachen Verweisen, die nicht mehr erreichbar sind)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// Disassociates a <see cref="Frame"/> previously registered by <see cref="RegisterFrame"/>
/// from <see cref="SessionState"/>. Any navigation state previously captured will be
/// removed.
/// </summary>
/// <param name="frame">An instance whose navigation history should no longer be
/// managed.</param>
public static void UnregisterFrame(Frame frame)
{
// Remove session state and remove the frame from the list of frames whose navigation
// state will be saved (along with any weak references that are no longer reachable)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// Desasocia un <see cref="Frame"/> previamente registrado mediante <see cref="RegisterFrame"/>
/// de <see cref="SessionState"/>. Todo estado de navegación previamente capturado se
/// quitará.
/// </summary>
/// <param name="frame">Instancia cuyo historial de navegación debería dejar de ser
/// administrado.</param>
public static void UnregisterFrame(Frame frame)
{
// Quitar estado de la sesión y quitar el marco de la lista de marcos cuyo estado
// de navegación se guardará (junto con cualquier referencia débil que haya dejado de estar accesible)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// Permet de stocker l'état de session associé au <see cref="Frame"/> spécifié.
/// L'état de session des frames inscrits précédemment à l'aide de <see cref="RegisterFrame"/> est
/// enregistré et restauré automatiquement dans le cadre du
/// <see cref="SessionState"/> global. Les frames qui ne sont pas inscrits ont un état transitoire
/// qui peut néanmoins être utile lors de la restauration de pages qui ont été supprimées du
/// cache de navigation.
/// </summary>
/// <remarks>Les applications peuvent utiliser <see cref="LayoutAwarePage"/> pour gérer
/// l'état spécifique aux pages, au lieu de gérer directement l'état de session de frames.</remarks>
/// <param name="frame">Instance pour laquelle l'état de session est requis.</param>
/// <returns>Collection d'états pour lequel est utilisé le même mécanisme de sérialisation que
/// <see cref="SessionState"/>.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// Les frames inscrits reflètent l'état de session correspondant
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// Les frames non inscrits ont un état transitoire
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// Inscrit une instance de <see cref="Frame"/> pour que son historique de navigation puisse être enregistré dans
/// et restauré à partir de <see cref="SessionState"/>. Les frames doivent être inscrits une seule fois,
/// immédiatement après la création s'ils doivent participer à la gestion de l'état de session. Lors de
/// l'inscription, si l'état a déjà été restauré pour la clé spécifiée,
/// l'historique de navigation est immédiatement restauré. Les appels ultérieurs de
/// <see cref="RestoreAsync"/> restaurent également l'historique de navigation.
/// </summary>
/// <param name="frame">Instance dont l'historique de navigation doit être géré par
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">Clé unique dans <see cref="SessionState"/> utilisée pour
/// enregistrer des informations relatives à la navigation.</param>
public static void RegisterFrame(Frame frame, String sessionStateKey)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
// Utilise une propriété de dépendance pour associer la clé de session à un frame et conserver une liste des frames dont
// l'état de navigation doit être géré
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// Vérifie si l'état de navigation peut être restauré
RestoreFrameNavigationState(frame);
}
/// <summary>
/// <see cref="SessionState"/> から <see cref="RegisterFrame"/> によって以前登録された <see cref="Frame"/> の関連付けを解除します。
/// 以前キャプチャされたナビゲーション状態は
/// 削除されます。
/// </summary>
/// <param name="frame">ナビゲーション履歴を管理する必要がなくなった
/// 管理されます。</param>
public static void UnregisterFrame(Frame frame)
{
// セッション状態を削除し、(到達不能になった弱い参照と共に) ナビゲーション状態が保存される
// フレームの一覧からフレームを削除します
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// Registra un'istanza di <see cref="Frame"/> per consentire il salvataggio e il ripristino della
/// cronologia di navigazione da <see cref="SessionState"/>. I frame devono essere registrati una volta
/// subito dopo la creazione se partecipano alla gestione dello stato sessione. Alla
/// registrazione, se lo stato è già stato ripristinato per la chiave specificata,
/// verrà subito ripristinata la cronologia di navigazione. I successivi richiami di
/// <see cref="RestoreAsync"/> ripristineranno anche la cronologia di navigazione.
/// </summary>
/// <param name="frame">Istanza la cui cronologia di navigazione deve essere gestita da
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">Chiave univoca in <see cref="SessionState"/> utilizzata per
/// archiviare le informazioni correlate alla navigazione.</param>
/// <param name="sessionBaseKey">Chiave facoltativa che identifica il tipo di sessione.
/// Può essere utilizzata per distinguere i diversi scenari di avvio dell'applicazione.</param>
public static void RegisterFrame(Frame frame, String sessionStateKey, String sessionBaseKey = null)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
if (!string.IsNullOrEmpty(sessionBaseKey))
{
frame.SetValue(FrameSessionBaseKeyProperty, sessionBaseKey);
sessionStateKey = sessionBaseKey + "_" + sessionStateKey;
}
// Utilizzare una proprietà di dipendenza per associare la chiave di sessione a un frame e conservare un elenco di frame di cui
// deve essere gestito lo stato di navigazione
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// Verificare se lo stato di navigazione può essere ripristinato
RestoreFrameNavigationState(frame);
}
/// <summary>
/// 針對與指定之 <see cref="Frame"/> 關聯的工作階段狀態，提供儲存體。
/// 之前在 <see cref="RegisterFrame"/> 中註冊的框架會
/// 將工作階段狀態自動與全域 <see cref="SessionState"/> 一起
/// 儲存和還原。未註冊的框架有暫時狀態，這些狀態
/// 在還原已從導覽快取捨棄的頁面時
/// 仍然有用。
/// </summary>
/// <remarks>應用程式可選擇依賴 <see cref="LayoutAwarePage"/> 來管理
/// 頁面特定狀態，而不直接處理框架工作階段狀態。</remarks>
/// <param name="frame">需要工作階段狀態的執行個體。</param>
/// <returns>狀態集合，受限於與
/// <see cref="SessionState"/> 相同的序列化機制。</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// 註冊的框架會反映對應的工作階段狀態
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// 未註冊的框架有暫時狀態
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// 將之前由 <see cref="RegisterFrame"/> 註冊的 <see cref="Frame"/>
/// 與 <see cref="SessionState"/> 取消關聯。之前擷取的任何導覽狀態都將
/// 移除。
/// </summary>
/// <param name="frame">不應該再管理之導覽記錄的
/// 執行個體。</param>
public static void UnregisterFrame(Frame frame)
{
// 移除工作階段狀態，並將框架從儲存導覽狀態的
// 框架清單移除 (以及不能夠再使用的任何弱式參考)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// 註冊 <see cref="Frame"/> 執行個體，讓它的導覽記錄能夠儲存到
/// <see cref="SessionState"/> 或從這裡還原。框架應在建立後立即註冊，
/// 這樣才能參與工作階段狀態管理。註冊後，
/// 如果為指定的索引鍵還原狀態，
/// 就會立即還原導覽記錄。之後引動
/// <see cref="RestoreAsync"/> 也會還原導覽記錄。
/// </summary>
/// <param name="frame">執行個體，其導覽記錄應由
/// <see cref="SuspensionManager"/> 管理</param>
/// <param name="sessionStateKey"><see cref="SessionState"/> 的唯一索引鍵，用來
/// 儲存導覽相關資訊。</param>
public static void RegisterFrame(Frame frame, String sessionStateKey)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
// 使用相依性屬性將工作階段索引鍵與框架產生關聯，並保存應管理
// 導覽狀態的框架清單
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// 檢查能否還原導覽狀態
RestoreFrameNavigationState(frame);
}
public static void UnregisterFrame(Frame frame)
{
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// Fornece armazenamento para o estado de sessão associado ao <see cref="Frame"/> especificado.
/// Quadros que foram previamente registrados com <see cref="RegisterFrame"/> possuem
/// seus estados de sessão salvos e restaurados automaticamente como parte do global
/// <see cref="SessionState"/>. Quadros que não estão registrados possuem estado transiente
/// que ainda pode ser útil ao restaurar páginas que foram descartadas do
/// cache de navegação.
/// </summary>
/// <remarks>Os aplicativos podem optar por depender do <see cref="NavigationHelper"/> para gerenciar
/// estado específico de página em vez de trabalhar diretamente com o estado da sessão do quadro.</remarks>
/// <param name="frame">A instância para a qual o estado da sessão é desejado.</param>
/// <returns>Uma coleção de estados sujeita ao mesmo mecanismo de serialização que
/// <see cref="SessionState"/>.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// Quadros registrados refletem o estado da sessão correspondente
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// Quadros que não estão registrados possuem estado transiente
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// Предоставляет хранилище для состояния сеанса, связанного с указанным объектом <see cref="Frame"/>.
/// Состояние сеанса фреймов, ранее зарегистрированных с помощью <see cref="RegisterFrame"/>,
/// сохраняется и восстанавливается автоматически в составе глобального объекта
/// <see cref="SessionState"/>. Незарегистрированные фреймы имеют переходное состояние,
/// которое, тем не менее, можно использовать при восстановлении страниц, удаленных из
/// кэша навигации.
/// </summary>
/// <remarks>Приложения могут использовать <see cref="NavigationHelper"/> для управления
/// состоянием, относящимся к странице, вместо непосредственного обращения к состоянию сеанса фрейма.</remarks>
/// <param name="frame">Экземпляр, для которого требуется состояние сеанса.</param>
/// <returns>Коллекция состояния, к которой применяется такой же механизм сериализации, как к объекту
/// <see cref="SessionState"/>.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// Зарегистрированные фреймы отражают соответствующее состояние сеанса
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// Незарегистрированные фреймы имеют переходное состояние
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// <see cref="Frame"/> インスタンスを登録し、ナビゲーション履歴を <see cref="SessionState"/> に保存して、
/// ここから復元できるようにします。
/// フレームは、セッション状態管理に参加する場合、作成直後に 1 回登録する必要があります。
/// 登録されしだい、指定されたキーに対して状態が既に復元されていれば、
/// ナビゲーション履歴が直ちに復元されます。
/// <see cref="RestoreAsync"/> はナビゲーション履歴も復元します。
/// </summary>
/// <param name="frame">ナビゲーション履歴を管理する必要があるインスタンスです
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">ナビゲーション関連情報を格納するのに
/// 使用される <see cref="SessionState"/> への一意キーです。</param>
public static void RegisterFrame(Frame frame, String sessionStateKey)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
// 依存関係プロパティを使用してセッション キーをフレームに関連付け、
// ナビゲーション状態を管理する必要があるフレームの一覧を保持します
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// ナビゲーション状態が復元可能かどうか確認します
RestoreFrameNavigationState(frame);
}
/// <summary>
/// Rimuove l'associazione a un oggetto <see cref="Frame"/> precedentemente registrato da <see cref="RegisterFrame"/>
/// da <see cref="SessionState"/>. Qualsiasi stato di navigazione precedentemente acquisito verrà
/// rimosso.
/// </summary>
/// <param name="frame">Istanza di cui non deve più essere gestita la cronologia di
/// navigazione.</param>
public static void UnregisterFrame(Frame frame)
{
// Rimuovere lo stato sessione e rimuovere il frame dall'elenco di frame di cui verrà salvato lo stato
// di navigazione (insieme ai riferimenti deboli che non sono più raggiungibili)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// 指定された <see cref="Frame"/> に関連付けられているセッション状態のストレージを提供します。
/// <see cref="RegisterFrame"/> で以前登録されたフレームには、
/// グローバルの <see cref="SessionState"/> の一部として自動的に保存および復元されるセッション状態があります。
/// 登録されていないフレームは遷移状態です。
/// 遷移状態は、ナビゲーション キャッシュから破棄されたページを復元する場合に
/// ナビゲーション キャッシュ。
/// </summary>
/// <remarks>アプリケーションは、フレームのセッション状態を直接処理するのではなく、<see cref="LayoutAwarePage"/> に依存して
/// ページ固有の状態を管理するように選択できます。</remarks>
/// <param name="frame">セッション状態が必要なインスタンスです。</param>
/// <returns><see cref="SessionState"/> と同じシリアル化機構の影響を受ける状態の
/// <see cref="SessionState"/>。</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// 登録されているフレームは、対応するセッション状態を反映します
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// 登録されていないフレームは遷移状態です
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// Fornisce l'archiviazione per lo stato sessione associato all'oggetto <see cref="Frame"/> specificato.
/// Per i frame precedentemente registrati con <see cref="RegisterFrame"/>, lo
/// stato sessione viene salvato e ripristinato automaticamente come parte dell'oggetto
/// <see cref="SessionState"/> globale. I frame non registrati hanno uno stato di passaggio
/// che può tuttavia essere utile quando vengono ripristinate le pagine eliminate dalla
/// cache di navigazione.
/// </summary>
/// <remarks>Le applicazioni possono scegliere di basarsi su <see cref="NavigationHelper"/> per gestire
/// lo stato specifico della pagina anziché gestire direttamente lo stato sessione del frame.</remarks>
/// <param name="frame">Istanza per cui si desidera lo stato sessione.</param>
/// <returns>Raccolta di stati soggetti allo stesso meccanismo di serializzazione di
/// <see cref="SessionState"/>.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// I frame registrati riflettono lo stato sessione corrispondente
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// I frame non registrati hanno uno stato di passaggio
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// Dissocie un <see cref="Frame"/> précédemment inscrit par <see cref="RegisterFrame"/>
/// de <see cref="SessionState"/>. Tout état de navigation précédemment capturé sera
/// supprimé.
/// </summary>
/// <param name="frame">Instance dont l'historique de navigation ne doit plus être
/// géré.</param>
public static void UnregisterFrame(Frame frame)
{
// Supprime l'état de session et supprime le frame de la liste des frames dont l'état de navigation
// sera enregistré (avec les références faibles qui ne sont plus accessibles)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// 注册 <see cref="Frame"/> 实例以允许将其导航历史记录保存到
/// <see cref="SessionState"/> 并从中还原。如果框架将参与会话状态管理，
/// 则应在创建框架后立即注册。在
/// 注册时，如果已还原指定键的状态，
/// 则将立即还原导航历史记录。
/// <see cref="RestoreAsync"/> 还将还原导航历史记录。
/// </summary>
/// <param name="frame">其导航历史记录应由
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey"><see cref="SessionState"/> 的唯一键，用于
/// 存储与导航相关的信息。</param>
public static void RegisterFrame(Frame frame, String sessionStateKey)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
// 使用依赖项属性可会话键与框架相关联，并记录其
// 导航状态应托管的框架
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// 查看导航状态是否可还原
RestoreFrameNavigationState(frame);
}
/// <summary>
/// Registra una instancia de <see cref="Frame"/> para permitir que su historial de navegación se guarde
/// y restaure desde <see cref="SessionState"/>. Los marcos deben registrarse una vez
/// inmediatamente tras su creación si van a participar en la administración del estado de sesión. Tras el
/// registro, si el estado ya se ha restaurado para la clave especificada,
/// se restaurará inmediatamente el historial de navegación. Las invocaciones subsiguientes de
/// <see cref="RestoreAsync"/> también restaurarán el historial de navegación.
/// </summary>
/// <param name="frame">Instancia cuyo historial de navegación debería administrarse mediante
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">Clave única de <see cref="SessionState"/> que se usa para
/// almacenar información relacionada con la navegación.</param>
public static void RegisterFrame(Frame frame, String sessionStateKey)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
// Usar una propiedad de dependencia para asociar la clave de sesión a un marco y mantener una lista de marcos cuyo
// estado de navegación deba administrarse
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// Comprobar si el estado de navegación puede restaurarse
RestoreFrameNavigationState(frame);
}
/// <summary>
/// 解除之前由 <see cref="RegisterFrame"/> 注册的 <see cref="Frame"/>
/// 与 <see cref="SessionState"/> 的关联。 之前捕获的任何导航状态都将
/// 已移除。
/// </summary>
/// <param name="frame">其导航历史记录不应再
/// 托管。</param>
public static void UnregisterFrame(Frame frame)
{
// 移除会话状态并移除框架列表中其导航
// 状态将被保存的框架(以及无法再访问的任何弱引用)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
/// <summary>
/// Proporciona almacenamiento para el estado de sesión asociado al <see cref="Frame"/> especificado.
/// El estado de sesión de los marcos registrados previamente en <see cref="RegisterFrame"/>
/// se guardó y restauró automáticamente como parte del
/// <see cref="SessionState"/> global. Los marcos no registrados tienen un estado transitorio
/// que puede ser útil al restaurar páginas descartadas de la
/// memoria caché de navegación.
/// </summary>
/// <remarks>Las aplicaciones pueden elegir basarse en <see cref="NavigationHelper"/> para administrar
/// el estado específico de página en lugar de trabajar directamente con el estado de sesión del marco.</remarks>
/// <param name="frame">Instancia para la que se desea obtener el estado de sesión.</param>
/// <returns>Colección de estados sujeta al mismo mecanismo de serialización que
/// <see cref="SessionState"/>.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// Los marcos registrados reflejan el estado de sesión correspondiente
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// Los marcos no registrados tienen un estado transitorio
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// 为与指定的 <see cref="Frame"/> 相关联的会话状态提供存储。
/// 之前已向 <see cref="RegisterFrame"/> 注册的框架已自动
/// 保存其会话状态且还原为全局
/// <see cref="SessionState"/> 的一部分。 未注册的框架具有
/// 在还原已从导航缓存中丢弃的页面时仍然有用的
/// 导航缓存。
/// </summary>
/// <remarks>应用程序可能决定依靠 <see cref="NavigationHelper"/> 管理
/// 特定于页面的状态，而非直接使用框架会话状态。</remarks>
/// <param name="frame">需要会话状态的实例。</param>
/// <returns>状态集合受限于与
/// <see cref="SessionState"/>。</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// 已注册框架反映相应的会话状态
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// 未注册框架具有瞬时状态
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// Registriert eine <see cref="Frame"/>-Instanz, um den zugehörigen Navigationsverlauf mithilfe von
/// <see cref="SessionState"/> speichern und wiederherstellen zu können. Rahmen sollten direkt nach der Erstellung
/// registriert werden, wenn diese Bestandteil der Verwaltung des Sitzungszustands sind. Wenn der
/// Zustand für den speziellen Schlüssel bereits wiederhergestellt wurde,
/// wird der Navigationsverlauf bei der Registrierung sofort wiederhergestellt. Bei nachfolgenden Aufrufen von
/// <see cref="RestoreAsync"/> wird der Navigationsverlauf ebenfalls wiederhergestellt.
/// </summary>
/// <param name="frame">Eine Instanz, deren Navigationsverlauf von
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">Ein eindeutiger Schlüssel in <see cref="SessionState"/> zum
/// Speichern von navigationsbezogenen Informationen.</param>
/// <param name="sessionBaseKey">Ein optionaler Schlüssel zum Identifizieren des Typs der Sitzung.
/// Damit können verschiedene Szenarien für den Anwendungsstart unterschieden werden.</param>
public static void RegisterFrame(Frame frame, String sessionStateKey, String sessionBaseKey = null)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
if (!string.IsNullOrEmpty(sessionBaseKey))
{
frame.SetValue(FrameSessionBaseKeyProperty, sessionBaseKey);
sessionStateKey = sessionBaseKey + "_" + sessionStateKey;
}
// Eine Abhängigkeitseigenschaft verwenden, um den Sitzungsschlüssel mit einem Rahmen zu verknüpfen, und eine Liste von Rahmen speichern, deren
// Navigationszustand verwaltet werden soll
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// Überprüfen, ob der Navigationszustand wiederhergestellt werden kann
RestoreFrameNavigationState(frame);
}
/// <summary>
/// Регистрация экземпляра <see cref="Frame"/>, чтобы обеспечить сохранение его журнала навигации в
/// объекте <see cref="SessionState"/> и восстановления журнала из этого объекта. Фреймы должны регистрироваться один раз
/// сразу после создания, если планируется включить их в управление состоянием сеанса. Если при
/// регистрации состояние для указанного ключа уже было восстановлено,
/// журнал навигации немедленно восстанавливается. Последовательные вызовы
/// <see cref="RestoreAsync"/> приведут к восстановлению журнала навигации.
/// </summary>
/// <param name="frame">Экземпляр, журнал навигации которого должен управляться диспетчером
/// <see cref="SuspensionManager"/></param>
/// <param name="sessionStateKey">Уникальный ключ в объекте <see cref="SessionState"/>, используемый для
/// хранения данных, связанных с навигацией.</param>
public static void RegisterFrame(Frame frame, String sessionStateKey)
{
if (frame.GetValue(FrameSessionStateKeyProperty) != null)
{
throw new InvalidOperationException("Frames can only be registered to one session state key");
}
if (frame.GetValue(FrameSessionStateProperty) != null)
{
throw new InvalidOperationException("Frames must be either be registered before accessing frame session state, or not registered at all");
}
// Свойство зависимостей используется для связывания сеансового ключа с фреймом и сохранения списка фреймов, состоянием навигации которых
// необходимо управлять
frame.SetValue(FrameSessionStateKeyProperty, sessionStateKey);
_registeredFrames.Add(new WeakReference<Frame>(frame));
// Проверяет возможность восстановления состояния навигации
RestoreFrameNavigationState(frame);
}
/// <summary>
/// Bietet Speichermöglichkeit für den Sitzungszustand, der mit dem angegebenen <see cref="Frame"/> verknüpft ist.
/// Für Rahmen, die zuvor mit <see cref="RegisterFrame"/> registriert wurden, wird der
/// Sitzungszustand automatisch als Teil des globalen <see cref="SessionState"/>
/// gespeichert und wiederhergestellt. Rahmen, die nicht registriert sind, verfügen über einen vorübergehenden Zustand,
/// der weiterhin nützlich sein kann, wenn Seiten wiederhergestellt werden, die aus dem
/// im Navigationscache verworfen wird.
/// </summary>
/// <remarks>Apps können beim Verwalten des seitenspezifischen Zustands auf <see cref="NavigationHelper"/> zurückgreifen,
/// anstatt direkt mit dem Rahmensitzungszustand zu arbeiten.</remarks>
/// <param name="frame">Die Instanz, für die der Sitzungszustand gewünscht wird.</param>
/// <returns>Eine Auflistung des Zustands, für den der gleiche Serialisierungsmechanismus wie für
/// <see cref="SessionState"/>.</returns>
public static Dictionary<String, Object> SessionStateForFrame(Frame frame)
{
var frameState = (Dictionary<String, Object>)frame.GetValue(FrameSessionStateProperty);
if (frameState == null)
{
var frameSessionKey = (String)frame.GetValue(FrameSessionStateKeyProperty);
if (frameSessionKey != null)
{
// Registrierte Rahmen geben den entsprechenden Sitzungszustand wieder.
if (!_sessionState.ContainsKey(frameSessionKey))
{
_sessionState[frameSessionKey] = new Dictionary<String, Object>();
}
frameState = (Dictionary<String, Object>)_sessionState[frameSessionKey];
}
else
{
// Rahmen, die nicht registriert sind, verfügen über einen vorübergehenden Zustand
frameState = new Dictionary<String, Object>();
}
frame.SetValue(FrameSessionStateProperty, frameState);
}
return frameState;
}
/// <summary>
/// Отменяет связь объекта <see cref="Frame"/>, ранее зарегистрированного с помощью <see cref="RegisterFrame"/>,
/// с объектом <see cref="SessionState"/>. Любое ранее записанное состояние навигации будет
/// удалено.
/// </summary>
/// <param name="frame">Экземпляр, управление журналом навигации которого должно быть
/// прекращено.</param>
public static void UnregisterFrame(Frame frame)
{
// Удаление состояние сеанса и удаление фрейма из списка фреймов, состояние навигации которых
// по-прежнему будет сохраняться (вместе со слабыми ссылками, которые перестанут быть доступными)
SessionState.Remove((String)frame.GetValue(FrameSessionStateKeyProperty));
_registeredFrames.RemoveAll((weakFrameReference) =>
{
Frame testFrame;
return !weakFrameReference.TryGetTarget(out testFrame) || testFrame == frame;
});
}
