앱 확장에 사용자 지정 속성 사용Using custom properties for app extensions

앱 확장 속성은 앱 매니페스트에서 앱 확장 개발자가 제공하는 사용자 지정 메타데이터 필드입니다.App extension properties are a custom metadata field provided by the app extension developer in their app manifest. 앱 확장 호스트는 앱 확장에서 콘텐츠를 로드 하지 않고도 앱 확장을 검사할 때 이 메타데이터를 읽을 수 있습니다.App extension hosts can read this metadata when examining app extensions without having to load any content from the app extension.

속성은 선택적이지만 매우 유용한 기능입니다.Properties are an optional but very useful feature. 앱 확장 호스트 플랫폼을 만들 때 필요할 수 있는 다양한 메타데이터를 사용할 수 있습니다(앱 확장을 로드하기 전에 확인하는 데 도움이 되는 버전, 기능, 지원되는 파일 형식의 목록 또는 기타 데이터).There are a wide range of possible metadata that you may require when creating an app extension host platform, such as version, capabilities, lists of supported file types or other data that is helpful to know prior to loading an app extension. 이러한 정보는 앱 확장을 로드하는 방법을 결정하기도 합니다.Such information may even determine how you load an app extension. 앱 확장 속성은 필요할 수도 있는 모든 필드를 예측하는 대신, 앱에 가장 적합한 방식으로 필요한 항목을 정확하게 정의하기 위해 오픈 캔버스를 제공합니다.Rather than trying to predict all of the fields you might need, app extension properties provide an open canvas to define exactly what you need in however manner best suited for your app.

앱 확장 속성의 장점Advantages of app extension properties

앱 확장 속성을 활용해야 하는 두 가지 중요한 이유가 있습니다.There two important reasons why you should take advantage of app extension properties:

  • 정보를 파일에 저장하지 않고도 앱 확장 플랫폼에 대한 기본 메타데이터 또는 중요한 메타데이터를 쉽고 안전하게 저장할 수 있습니다.It's an easy way and safe way to store basic or important metadata about your app extension platform without having to put that information into files. 버전 관리, 권한 및 적용과 같은 중요한 개념에 사용할 수 있습니다.You can use it for important concepts like versioning, permissions, and as enforcement. 예를 들어, 앱은 version 필드가 정의되어야 하며, 속성에 있어야 하고, 해당 값에 따라 다른 로드 동작이 발생할 수 있습니다.For example, your app could insist that a version field is defined and present in the properties, and have different loading behavior based on that value.

  • 정보는 앱 매니페스트에 저장되므로 나중에 API를 통해 인덱싱하여 사용할 수 있습니다.Because the information is stored in the app manifest, it can be indexed and made available via an API in the future. 즉, 사용자에게 표시되도록 버블링할 수 있으며, 확장을 먼저 배포하고 로드하지 않고도 특정 속성을 위해 더 구체화된 앱 확장 검색을 수행할 수도 있습니다.That means you can bubble it up for display to the user, or have more refined app extension searches for specific properties without having to deploy and load the extension first.

속성 선언 방법How to declare properties

속성은 패키지의 Package.appxmanifest 파일에 선언됩니다.Properties are declared in the Package.appxmanifest file in your package. 런타임 시 확장 호스트에서 속성 세트로 읽을 수 있습니다.They can be read at runtime by the extension host as a property set. 호스트는 플랫폼을 정의하므로, 사용할 수 있는 속성과 AppExtension 선언에 포함되어야 하는 속성에 대해 확장 개발자와 통신하는 것은 호스트에서 결정합니다.Because the host defines the platform, it is up to the host to communicate to the extension developers about which properties are available and should be put into the AppExtension declaration.

참고

Visual Studio의 매니페스트 디자이너는 속성을 정의하는 기능을 지원하지 않습니다.The manifest designer in Visual Studio does not support the ability to define properties. 속성을 정의하려면 Package.appxmanifest를 직접 편집해야 합니다.You must edit the Package.appxmanifest directly to define properties.

속성을 선언하려면 <uap3:AppExtension> 선언의 <uap3:Properties/> 요소에 배치합니다.To declare properties, put them in the <uap3:Properties/> element under your <uap3:AppExtension> declaration. Edge에서 지원하는 속성을 사용하는 Microsoft Edge에 대한 샘플 <uap3:AppExtension> 선언은 다음과 같습니다.Here is a sample <uap3:AppExtension> declaration for Microsoft Edge that uses properties supported by Edge.

<uap3:AppExtension Name="com.microsoft.edge.extension" Id="FirstExtension" PublicFolder="Extension" DisplayName="MyExtension">
  <uap3:Properties>
    <Capabilities>
      <Capability Name="websiteContent" />
      <Capability Name="websiteInfo" />
      <Capability Name="browserWebRequest" />
      <Capability Name="browserStorage" />
    </Capabilities>
  </uap3:Properties>
</uap3:AppExtension>

Edge에는 선언된 확장 기능 목록과 함께 Capabilities의 알려진 속성 값이 정의되어 있습니다.Edge has defined a known property value of Capabilities with a list of extension capabilities declared. 호스트는 앱 확장에서 원하는 모든 속성을 지원할 수 있습니다.As a host, you can support whatever properties you want in your app extensions. 이러한 속성은 속성 세트이므로 중첩된 속성을 가질 수도 있습니다.Since these are a property set, you can also have nested properties. 나중에 확장의 형식을 변경하는 경우 사용할 수 있는 루트 버전 속성이 있는 것이 좋습니다.Its a good idea to have a root version property that you can use in case you change formats of your extensions in the future. 의도적으로 Version을 앱 확장의 특성으로 두지 않았으므로 인위적으로 버전 관리 의미 체계만 사용해서는 안 됩니다.We intentionally did not put Version as an attribute of app extensions so you would not be artificially confined to using our versioning semantics. 대신, 여러 사용자 정의 특성 중 하나일 수 있는 속성을 원하는 방법 및 형식과 원하는 방식으로 생성했습니다.Instead, we created properties where version could be one of many custom-defined attributes, in whatever way and format you want, and processed however you want.

속성 사용 방법How to use properties

앱 확장에서 다음과 같은 버전을 설명하는 간단한 속성이 있다고 가정합니다.Suppose you have a simple property in an app extensions that describes a version, such as the following.

<uap3:Properties>
    <Version>1.0.0.0</Version>
</uap3:Properties>

런타임 시 이 데이터를 가져오려면 앱 확장에서 GetExtensionPropertiesAsync()를 호출하면 됩니다.To get this data at runtime, just call GetExtensionPropertiesAsync() on the app extensions.

string extensionVersion = "Unknown";
var properties = await ext.GetExtensionPropertiesAsync() as PropertySet;
if (properties != null)
{
    if (properties.ContainsKey("Version"))
    {
        PropertySet versionProperty = properties["Version"] as PropertySet;
        extensionVersion = versionProperty["#text"].ToString();
    }
}