com4:SurrogateServer

Article
10/30/2023

Registers a SurrogateServer with one or many class registrations.

Element hierarchy

<com4:SurrogateServer>

Syntax

<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>

Attributes and elements

Attributes

Attribute	Description	Data type	Required
CustomSurrogateExecutable	A path to the DllSurrogate in the AppId key. This path is relative to the package root and must reference a file in the package. This is mututally exclusive with SystemSurrogate.	A string with a value between 1 and 256 characters in length that must end with `.exe` and cannot contain these characters: `<`, `>`, `:`, `"`, `\|`, `?`, or `*`.	Yes
DisplayName	DisplayName is a localizable string corresponding to the default AppID key value.	A string with a value between 1 and 256 characters in length.	Yes
LaunchAndActivationPermission	An SDDL string that corresponds to the LaunchPermission value of the AppID key.	An SDDL string value.	Yes
AppId	The AppId that references the associated AppId key.	A GUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.	Yes
SystemSurrogate	A value that corresponds to well-known values from the DllSurrogate value of the AppId key. This is mututally exclusive with CustomSurrogateExecutable.	A string with the following optional value: "PreviewHost".	Yes

Child elements

Child element	Description
Class	Defines a surrogate server class registration.
InProcessServerClassReference	Specifies the class with which the managed in-process server is associated and sets registration details.
ClassReference	Specifies the class with which the registered in-process server is associated and sets registration details.

Parent elements

Parent element	Description
Extensions	Defines one or more extensibility points for the app.

Remarks

The CLSID Key](/windows/win32/com/clsid-key-hklm) in the COM registry layout enables a CLSID to be registered for inproc activation (CLSCTX_INPROC_SERVER) and for outofproc activation in a surrogate server (CLSCTX_LOCAL_SERVER) by specifying:

Inproc activation details in an InprocServer32 subkey.
A reference to an AppID key via the AppID value of the CLSID key, where the AppID key specifies a surrogate via the DllSurrogate value. Note that for outofproc activation in a surrogate server, the inproc server registration details, e.g. dll path and ThreadingModel, are also used in outofproc activation. The ClassReference child of the InProcessServer element enables a package that registers a CLSID for both inproc and outofproc activation to specify the inproc server details once, as an InProcessServer/Class or InProcessServer/ClassReference element, and reference this element from the SurrogateServer that supports outofproc activation of the CLSID. This structure for the inproc/outofproc registrations more closely reflects the COM registry layout than independently specifying the dll path and ThreadingModel in both InProcessServer/ClassReference and SurrogateServer/ClassReference elements.

When packaging an application with a CLSID registered for outofproc activation in a surrogate server, it is generally recommended that only the surrogate server is registered in the manifest. For example, surrogate registrations are often used to support COM-based extension points that historically enabled inproc server implementations but which now recommend an outofproc server registration as a best practice for isolation. For packaged applications, there are additional functional limitations for inproc servers (see In-ProcessServers for details), whereas any package with the runFullTrust restricted capability can successfully register a surrogate server, and for most extension points registering a surrogate server is sufficient to enable the functionality of the extension. However, if a packaged application needs to support inproc activation of its CLSIDs for compatibility with other applications that request inproc activation (CLSCTX_INPROC_SERVER), and satisfies the requirements for registering an inproc server, it can register the CLSID for inproc activation and outofproc activation in a surrogate. In this case, it is recommended to provide the inproc server details in an InProcessServer/Class or InProcessServer/ClassReference element, and reference them from a SurrogateServer/InProcessServerClassReference element.

Requirements

Item	Value
Namespace	`http://schemas.microsoft.com/appx/manifest/com/windows10/4`
Minimum OS Version	Windows 10 (Build 20348)

Share via