Delen via

Kwalificatie in MRM

  • Artikel

De resource-indexeerfunctie (en de MRT-runtime) gebruiken 'kwalificaties' om de context(en) te bepalen waarin een bepaalde resourcekandidaat moet worden gebruikt. Elke resource heeft een naam en een of meer kandidaten (of waarden) en elke kandidaat heeft nul of meer kwalificaties. Zie Resourcenamen in MRMvoor meer informatie over het benoemen van resources.

Er kan bijvoorbeeld een tekenreeksresource met de naam begroeting met drie verschillende kandidaten voor drie verschillende lokalisaties:

  • Voor engels, de tekst "Hallo"
  • Voor duits, de tekst "Hallo"
  • Voor Koreaans de tekst "안녕하세요"

Deze kandidaten worden toegevoegd aan de indexeerfunctie met de juiste taalkwalificaties en deze worden opgeslagen in het PRI-bestand, zodat MRT weet welke te gebruiken tijdens runtime. Als u bijvoorbeeld deze drie tekenreeksen wilt toevoegen aan een indexeerfunctie, kunt u het volgende gebruiken:

    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 */ }

Taal is slechts een van de mogelijke kwalificaties; andere algemene kwalificaties zijn Schaal (voor het opgeven van afbeeldingen met verschillende resoluties) of Contrast (voor verschillende contrastinstellingen). Een volledige lijst met kwalificaties wordt vermeld in het onderwerp ResourceContext.QualifierValues.

Houd er rekening mee dat de "korte" vorm van de kwalificaties (bijvoorbeeld "lang" in plaats van "taal") niet ondersteund door de MRM-API's; u moet de lange vorm gebruiken. De functies MrmIndexFileAutoQualifiers en MrmIndexResourceContainerAutoQualifiers die kwalificaties van bestandspaden afleiden, ondersteunen echter de korte formulieren.

Kwalificaties worden opgegeven als tekenreeksen in de vorm name-value, zoals language-en of scale-200. (De waarden voor een Language kwalificatie kunnen ook afbreekstreepjes bevatten, zoals en-us.) Zowel de naam als de waarde zijn niet hoofdlettergevoelig, dus LANGUAGE-EN-US, Language-En-Usen language-en-us zijn allemaal gelijkwaardig.

Let op: het is een fout bij het opgeven van twee kandidaten voor dezelfde resource met dezelfde kwalificaties, maar verschillende waarden. Helaas is deze fout niet weergegeven wanneer resources worden toegevoegd aan de indexeerfunctie (bijvoorbeeld wanneer MrmIndexString) wordt aangeroepen, maar op het moment dat het PRI-bestand wordt gegenereerd, wordt ERROR_MRM_DUPLICATE_ENTRY geretourneerd, maar wordt er geen indicatie weergegeven van welke resource het probleem heeft veroorzaakt.

Dit codefragment slaagt bijvoorbeeld bij het toevoegen van een dubbele kandidaat, maar mislukt later tijdens het genereren van PRI:

// 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);

Als dezelfde kandidaat twee keer wordt toegevoegd (bijvoorbeeld in de bovenstaande code, als de tweede aanroep 'rood' wordt herhaald in plaats van 'blauw'), wordt het duplicaat genegeerd en wordt er geen fout gegenereerd.

Kwalificatielijsten

Resourcekandidaten kunnen meer dan één kwalificatie hebben. Afbeeldingsbestanden hebben bijvoorbeeld kandidaten nodig op basis van zowel Schaal (100%, 200%, enzovoort) als Contrast (standaard of hoog). Als de afbeelding tekst bevat, moet deze mogelijk ook worden gekwalificeerd op basis van Language.

Er worden meerdere kwalificaties opgegeven in één tekenreeks, gescheiden door onderstrepingstekens. Een afbeeldingskandidaat voor hoog contrast op 200% geschaald, gebruikt bijvoorbeeld de kwalificatie contrast-high_scale-200. De volgorde waarin kwalificaties in de lijst worden opgegeven, maakt niet uit; MRT heeft een ingebouwde volgorde van belang voor elke kwalificatie (bijvoorbeeld Taal is belangrijker dan Schaal).

Hoewel het geen fout is om een kwalificatie te herhalen in een kwalificatielijst (zelfs met verschillende waarden), worden alle behalve de eerste genegeerd.

  • language-en_language-en (geef engels tweemaal op - effectieve taal is Engels)
  • language-en_language-de (geef Engels op dan Duits - effectieve taal is Engels)
  • language-de_language-en (geef Duits op dan Engels - effectieve taal is Duits)

Zoals hierboven vermeld, is het een fout om twee resourcekandidaten met dezelfde kwalificatie toe te voegen, maar verschillende waarden. Dit is ongeacht de volgorde van de kwalificatielijsten in een kwalificatielijst.

Neutrale kandidaten

Wanneer u resourcekandidaten toevoegt aan de indexeerfunctie, kunt u een emptry-tekenreeks (of null-aanwijzer) opgeven als kwalificatie om aan te geven dat de kandidaat 'neutraal' is en elke context kan vinden. De naam van de app die wordt weergegeven in het startmenu kan bijvoorbeeld een neutrale kandidaat zijn omdat app-namen doorgaans niet zijn gelokaliseerd (en ze zijn niet afhankelijk van andere zaken zoals Schalen of Contrast). Neutrale kandidaten kunnen naast specifieke kandidaten, indien gewenst, worden gebruikt.

Bijvoorbeeld:

// 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");

Standaardkwalificaties

Bij het maken van een configuratiebestand (via een van de MrmCreateConfig... functies) of het maken van een resourceindexeerfunctie (via een van de MrmCreateResourceIndexer... functies) Zijn de defaultQualifiers de kwalificaties (zoals taal) die aangeven dat de resourcekandidaten moeten worden gebruikt als er geen betere overeenkomsten kunnen worden gevonden. Als een app bijvoorbeeld resources in het Engels en Frans heeft, maar deze wordt uitgevoerd op het systeem met de taal die is ingesteld op Japans, wordt de taal die is opgegeven als de standaardkwalificatie wanneer het PRI-bestand is gemaakt, gebruikt. De standaardkwalificaties bepalen ook welke taal en schaal moeten worden gebruikt om het belangrijkste PRI-bestand te maken bij het gebruik van AutoSplit verpakking (zie MrmPackagingMode voor meer informatie).

Houd er rekening mee dat alle resources een kandidaat moeten hebben die is opgegeven met de standaardkwalificaties (of een neutrale kandidaat), anders zou er niets terugvallen voor het geval er geen beste overeenkomst was. Houd er rekening mee dat het niet mogelijk is om een terugvalkandidaat te bieden, niet beschouwd als een fout (de indexeerfunctie genereert een kandidaat voor lege tekenreeksen voor u), maar dit kan leiden tot een slechte gebruikerservaring of toepassingsfouten.