Freigeben über

Qualifizierer in MRM

  • Artikel

Der Ressourcenindexer (und die MRT-Laufzeit) verwenden „Qualifizierer”, um den Kontext(n) zu bestimmen, in dem ein bestimmter Ressourcenkandidat verwendet werden soll. Jede Ressource hat einen Namen und einen oder mehrere Kandidaten (oder Werte), und jeder Kandidat verfügt über null oder mehr Qualifizierer. Weitere Informationen zum Benennen von Ressourcen finden Sie unter Ressourcennamen in MRM.

Zum Beispiel kann es eine Zeichenfolgenressource namens Begrüßung mit drei verschiedenen Kandidaten für drei verschiedene Lokalisierungen geben:

  • Für Englisch, der Text „Hello”
  • Für Deutsch, der Text „Hallo”
  • Für Koreanisch den Text „안녕하세요”

Diese Kandidaten werden dem Indexer mit den richtigen Sprachqualifizierern hinzugefügt, und diese werden in der PRI-Datei gespeichert, sodass MRT weiß, welcher zur Laufzeit verwendet werden soll. Wenn Sie z. B. diese drei Zeichenfolgen zu einem Indexer hinzufügen möchten, kann folgendes verwendet werden:

    HRESULT hr{};
    hr = MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hello", L"language-en");
    hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hallo", L"language-de");
    hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"안녕하세요", L"language-ko");
    if (FAILED(hr)) { /* error handling */ }

Die Sprache ist nur eine der möglichen Qualifizierer. Andere allgemeine Qualifizierer umfassen Skalierung (zum Angeben von Bildern mit unterschiedlichen Auflösungen) oder Kontrast (für unterschiedliche Kontrasteinstellungen). Eine vollständige Liste der Qualifizierer ist im Thema ResourceContext.QualifierValues aufgeführt.

Beachten Sie, dass die „kurze” Form der Qualifizierer (z. B. „lang” anstelle von „Sprache”) von den MRM-APIs nicht unterstützt wird. Sie müssen das lange Formular verwenden. Dennoch unterstützen die Funktionen MrmIndexFileAutoQualifiers und MrmIndexResourceContainerAutoQualifier, die Qualifizierer aus Dateipfaden ableiten, unterstützen die kurzen Formulare.

Qualifizierer werden als Zeichenfolgen in der Form name-value angegeben, z. B. language-en oder scale-200. (Die Werte für ein Sprachqualifizierer können auch Bindestriche enthalten, z. B. en-us.) Sowohl der Name als auch der Wert werden ohne Groß-/Kleinschreibung unterschieden, sodass LANGUAGE-EN-USLanguage-En-Us, und language-en-us alle gleichwertig sind.

Beachten Sie, dass es sich um einen Fehler handelt, um zwei Kandidaten für dieselbe Ressource mit denselben Qualifizierern, aber unterschiedlichen Werten anzugeben. Leider wird dieser Fehler nicht angezeigt, wenn Ressourcen dem Indexer (z. B. beim Aufrufen von MrmIndexString) hinzugefügt werden, aber zum Zeitpunkt der Erstellung der PRI-Datei wird die Generierung ERROR_MRM_DUPLICATE_ENTRY zurückgeben, aber keine Angabe angegeben, welche Ressource das Problem verursacht hat.

Dieser Codeausschnitt wird beispielsweise erfolgreich ausgeführt, wenn er einen doppelten Kandidaten hinzufügt, später aber während der PRI-Generierung fehlschlägt:

// Add "color = red". Returns S_OK, since all arguments are valid.
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"red", L"language-en"); 
// Add "color = blue". Returns S_OK, since all arguments are valid (in isolation).
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"blue", L"language-en"); 

// Fails with ERROR_MRM_DUPLICATE_ENTRY since there are two English candidates for "strings/color" 
// ("red" and "blue"). 
hr = MrmCreateResourceFile(indexer, MrmPackagingModeStandaloneFile, MrmPackagingOptionsNone, fileName);

Wenn der gleiche Kandidat zweimal hinzugefügt wird (z. B. im obigen Code, wenn der zweite Aufruf wiederholt „rot” anstelle von „blau”) wird das Duplikat ignoriert, und es wird kein Fehler generiert.

Qualifiziererlisten

Ressourcenkandidaten können mehrere Qualifizierer haben. Bilddateien benötigen z. B. Kandidaten basierend auf Skalierung (100%, 200%, etc.) und Kontrast (Standard oder hoch). Wenn das Bild Text enthält, muss es möglicherweise auch basierend auf der Sprache qualifiziert werden.

Mehrere Qualifizierer werden in einer einzelnen Zeichenfolge angegeben, getrennt durch Unterstriche. Ein Bildkandidat für hohen Kontrast mit einer Skalierung von 200 % würde z. B. den Qualifizierer contrast-high_scale-200 verwenden. Die Reihenfolge, in der Qualifizierer in der Liste angegeben sind, spielt keine Rolle; MRT verfügt über eine integrierte Reihenfolge der Wichtigkeit für jeden Qualifizierer (z. B. Sprache ist wichtiger als Skalierung).

Obwohl es kein Fehler ist, einen Qualifizierer in einer Qualifiziererliste (auch mit unterschiedlichen Werten) zu wiederholen, werden alle, aber der Erste ignoriert.

  • language-en_language-en (Geben Sie Englisch zweimal an – effektive Sprache ist Englisch)
  • language-en_language-de (Geben Sie Englisch an, dann Deutsch – effektive Sprache ist Englisch)
  • language-de_language-en (Geben Sie Deutsch an, dann Englisch – effektive Sprache ist Deutsch)

Wie oben erwähnt, ist es ein Fehler, zwei Ressourcenkandidaten mit denselben Qualifizierern, aber unterschiedlichen Werten hinzuzufügen. Dies ist unabhängig von der Reihenfolge der Qualifizierer in einer Qualifiziererliste.

Neutrale Kandidaten

Wenn Sie dem Indexer Ressourcenkandidaten hinzufügen, können Sie eine emptry-Zeichenfolge (oder einen NULL-Zeiger) als Qualifizierer angeben, um anzugeben, dass der Kandidat „neutral” ist und einem beliebigen Kontext entsprechen kann. Der Name der in der Menü angezeigten App kann z. B. ein neutraler Kandidat sein, da App-Namen normalerweise nicht lokalisiert werden (und sie hängen nicht von anderen Elementen wie Skalierung oder Kontrast ab). Neutrale Kandidaten können bei Bedarf zusätzlich zu bestimmten Kandidaten verwendet werden.

Zum Beispiel:

// The name of the app is the same, regardless of language, scale, etc.
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppName", L"Contoso Widgets", nullptr); 

// The name of the publisher is always "Contoso Inc." except in Australia, where it is "Contoso PTY LTD".
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso Inc.", nullptr); 
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso PTY LTD", L"homeregion-au");

Standardqualifizierer

Beim Erstellen einer Konfigurationsdatei (über eine der MrmCreateConfig...-Funktionen) oder beim Erstellen eines Ressourcenindexers (über eine der MrmCreateResourceIndexer...-Funktionen) sind die Standardqualifizierer die Qualifizierer (z. B. Sprache), die die zu verwendenden Ressourcenkandidaten angeben, wenn keine besseren Übereinstimmungen gefunden werden können. Wenn eine App z. B. Ressourcen in Englisch und Französisch aufweist, aber auf dem System ausgeführt wird, in dem die Sprache auf Japanisch festgelegt ist, wird die Sprache verwendet, die als „Standardqualifizierer” angegeben ist, wenn die PRI-Datei erstellt wurde. Die Standardqualifizierer bestimmen außerdem, welche Sprache und Skalierung zum Erstellen der PRI-Hauptdatei bei Verwendung von AutoSplit-Verpackungen verwendet werden soll (weitere Informationen finden Sie unter MrmPackagingMode).

Beachten Sie, dass für alle Ressourcen ein Kandidat mit den Standardqualifizierer (oder ein neutraler Kandidat) angegeben werden sollte, da sonst nichts zur Verfügung steht, auf das man zurückgreifen könnte, falls es keine beste Übereinstimmung gibt. Beachten Sie, dass das Fehlen eines Fallback-Kandidaten nicht als Fehler angesehen wird (der Indexer generiert einen Kandidaten mit leerer Zeichenfolge für Sie), aber es kann zu einer schlechten Benutzererfahrung oder Anwendungsfehlern führen.