com4 :SurrogateServer

Article
10/30/2023

Inscrit un SurrogateServer avec une ou plusieurs inscriptions de classes.

Hiérarchie d’éléments

<com4 :SurrogateServer>

Syntaxe

<com4:SurrogateServer
  CustomSurrogateExecutable = 'A string with a value between 1 and 256 characters in length that must end with ".exe" and cannot contain these characters: <, >, :, ", |, ?, or *.'
  DisplayName = 'A string with a value between 1 and 256 characters in length. This string is localizable.'
  LaunchAndActivationPermission = 'An [SDDL string](/windows/win32/secauthz/security-descriptor-string-format) value.'
  AppId = 'A GUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.'
  SystemSurrogate = 'A string with the following optional value: "PreviewHost".' >

  <!-- Child elements -->
  Class
  InProcessServerClassReference
  ClassReference

</com4:SurrogateServer>

Attributs et éléments

Attributs

Attribut	Description	Type de données	Obligatoire
CustomSurrogateExecutable	Chemin d’accès au DllSurrogate dans la clé AppId. Ce chemin est relatif à la racine du package et doit référencer un fichier dans le package. Cette option est mututally exclusive avec SystemSurrogate.	Chaîne avec une valeur comprise entre 1 et 256 caractères qui doit se terminer `.exe` par et ne peut pas contenir les caractères suivants : `<`, `>`, `":`, `\|`, , `?`ou `*`.	Yes
DisplayName	DisplayName est une chaîne localisable correspondant à la valeur de clé AppID par défaut.	Chaîne dont la valeur est comprise entre 1 et 256 caractères.	Yes
LaunchAndActivationPermission	Chaîne SDDL qui correspond à la valeur LaunchPermission de la clé AppID.	Valeur de chaîne SDDL .	Yes
AppID	AppId qui fait référence à la clé AppId associée.	GUID sous la forme xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.	Yes
SystemSurrogate	Valeur qui correspond aux valeurs connues de la valeur DllSurrogate de la clé AppId. Cette option est exclusivement exclusive avec CustomSurrogateExecutable.	Chaîne avec la valeur facultative suivante : « PreviewHost ».	Yes

Éléments enfants

Élément enfant	Description
Classe	Définit une inscription de classe de serveur de substitution.
InProcessServerClassReference	Spécifie la classe à laquelle le serveur in-process managé est associé et définit les détails d’inscription.
ClassReference	Spécifie la classe à laquelle le serveur in-process inscrit est associé et définit les détails d’inscription.

Éléments parents

Élément parent	Description
Extensions	Définit un ou plusieurs points d’extensibilité pour l’application.

Remarques

La clé CLSID](/windows/win32/com/clsid-key-hklm) dans la disposition du Registre COM permet d’inscrire un CLSID pour l’activation inproc (CLSCTX_INPROC_SERVER) et pour l’activation outofproc dans un serveur de substitution (CLSCTX_LOCAL_SERVER) en spécifiant :

Détails d’activation inproc dans une sous-clé InprocServer32 .
Référence à une clé AppID via la valeur AppID de la clé CLSID, où la clé AppID spécifie un substitut via la valeur DllSurrogate . Notez que pour l’activation de l’outofproc dans un serveur de substitution, les détails d’inscription du serveur inproc, par exemple le chemin d’accès dll et ThreadingModel, sont également utilisés dans l’activation outofproc. L’enfant ClassReference de l’élément InProcessServer permet à un package qui inscrit un CLSID pour l’activation inproc et outofproc de spécifier une fois les détails du serveur inproc, en tant qu’élément InProcessServer/Class ou InProcessServer/ClassReference , et référencer cet élément à partir du SurrogateServer qui prend en charge l’activation outofproc du CLSID. Cette structure pour les inscriptions inproc/outofproc reflète plus étroitement la disposition du Registre COM que la spécification indépendante du chemin d’accès dll et de ThreadingModel dans les éléments InProcessServer/ClassReference et SurrogateServer/ClassReference.

Lors de l’empaquetage d’une application avec un CLSID inscrit pour l’activation outofproc dans un serveur de substitution, il est généralement recommandé que seul le serveur de substitution soit inscrit dans le manifeste. Par exemple, les inscriptions de substitution sont souvent utilisées pour prendre en charge les points d’extension COM qui ont historiquement activé les implémentations de serveur inproc, mais qui recommandent désormais une inscription de serveur outofproc comme meilleure pratique pour l’isolation. Pour les applications empaquetées, il existe des limitations fonctionnelles supplémentaires pour les serveurs inproc (voir In-ProcessServers pour plus d’informations), alors que tout package avec la fonctionnalité limitée runFullTrust peut inscrire correctement un serveur de substitution et, pour la plupart des points d’extension, l’inscription d’un serveur de substitution est suffisante pour activer la fonctionnalité de l’extension. Toutefois, si une application empaquetée doit prendre en charge l’activation inproc de ses CLSID pour la compatibilité avec d’autres applications qui demandent l’activation inproc (CLSCTX_INPROC_SERVER), et qu’elle remplit les conditions requises pour l’inscription d’un serveur inproc, elle peut inscrire le CLSID pour l’activation inproc et l’activation outofproc dans une substitution. Dans ce cas, il est recommandé de fournir les détails du serveur inproc dans un élément InProcessServer/Class ou InProcessServer/ClassReference , et de les référencer à partir d’un élément SurrogateServer/InProcessServerClassReference .

Configuration requise

Élément	Valeur
Espace de noms	`http://schemas.microsoft.com/appx/manifest/com/windows10/4`
Minimum OS Version	Windows 10 (build 20348)