Draft API proposal for #888 Support for UWP callers and a non command line interface API

[sreadingMSFT]

I'll be sharing this with the API design review team and will update this when that review has a scheduled date.

See the Files Changed tab for the Com Api.md.

Microsoft Reviewers: Open in CodeFlow

[github-actions]

Misspellings found, please review:

• abifind
• IApp
• IFind
• IGet
• iinstall
• implememented
• MIDL
• pseudocode
• runtimeclass
• UAC
• Xaml

To accept these changes, run the following commands from this repository on this branch

pushd $(git rev-parse --show-toplevel)
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"IInstalled validator valijson valueiterator "');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
  if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
  next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
make_path ".github/actions/spelling";
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"abifind IApp IFind IGet iinstall implememented MIDL pseudocode runtimeclass UAC Xaml "');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a) cmp lc($b)} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;'
popd

[jsoref]

The other items should just be added to expect.txt/allow.txt

[github-actions]

Misspellings found, please review:

• apicontract
• contractversion
• rclsid
• recieve
• REFCLSID
• TOutput

To accept these changes, run the following commands from this repository on this branch

pushd $(git rev-parse --show-toplevel)
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"validator valijson valueiterator "');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
  if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
  next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
make_path ".github/actions/spelling";
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"apicontract contractversion rclsid recieve REFCLSID TOutput "');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a) cmp lc($b)} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;'
popd

[jonwis]

Seems OK to start API review, invite coming soon.

[jonwis]

Oopsie, you're right.

[jonwis]

See https://www.osgwiki.com/wiki/WinRT_API_Design_Guidelines#Specifying_Asynchronous_Operation_Objects_in_IDL (non-MSFT folks, I hope to have these publicly visible soon) for how to do it. The issue is that we want people to not wrap all their operations in try/catch. When an operation fails and returns an hresult it generates an exception in most langauges, so you'd have to write this:

AppCatalog ac{nullptr};
winrt::hresult ecode;
try {
    ac = co_await foo.FindSource(sourceName);
} catch (winrt::hresult_exception const& ex) {
    ecode = ex.code();
}
if (!ac) {
    // do something with 'ecode'
} else {
    // catalog ready
}

Compare that to:

FindAppCatalogResult found = co_await thing.FindSource(sourceName);
if (found.Catalog) {
    // use found.Catalog
} else {
    switch (found.Status()) {
    case FindCatalogResultStatus::AccessDenied:
    case FindCatalogResultStatus::NotFound:
    case FindCatalogResultStatus::ServerError:
    case FindCatalogResultStatus::MalformedResponse:
        // do whatever with those
        return;
    case FindCatalogResultStatus::Unknown:
        // Send telemetry using found.ExtendedError();
        return;
    }
}

[jonwis]

API review Left off on about line 486.

[jonwis]

CONSIDER: Ask COM team if it's possible to have a DLL from the package loaded into the packaged-COM client to put the "brains" of the option object into the client side.

CONSIDER: Define a "low level" valueset based interface, and there's a Reunion wrapper that has the better thing that can be loaded into the caller.

[jonwis]

DISCUSSION: Yes, we should look into how we can reduce this set of calls

[github-actions]

Misspellings found, please review:

• contoso
• msdn
• pkgmgr

To accept these changes, run the following commands from this repository on this branch

pushd $(git rev-parse --show-toplevel)
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"MIDL validator valijson valueiterator "');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
  if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
  next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
make_path ".github/actions/spelling";
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"contoso midl msdn pkgmgr "');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a) cmp lc($b)} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;'
popd

[jonwis]

DISCUSSION: This is set when someone adds a catalog at the command line. It should be an open-ended set.

RECOMMEND: Use the KnownFoo pattern, where you have KnownAppCatalogKinds::Rest which is a static property whose value can be assigned here. (Apply this more places.)

[jonwis]

Recommend: Use the KnownAppInstallerKinds pattern here as well

[jonwis]

DISCUSSION: See earlier comments about CoCreate vs RoActivate here

[JohnMcPMS]

@sreadingMSFT , can we get the spelling fixes and merge this?

[denelon]

#888