microsoftdocs / winrt-api Goto Github PK

I noticed that in a XAML app, if you create an animation with an EasingDoubleKeyFrame but don't specify an easing function via the EasingFunction property, the system applies a default Bezier curve. This was unexpected since you would expect a linear ease in this case.

Please document what the default easing function will be if you do not supply one.

/winrt-api/windows.web.http/httpclient.md
Line 70

httpclient.Dispose(); => httpClient.Dispose();

The document of StorageFolder.GetFilesAsync() says that it only throws UnauthorizedAccessException. But it also throws ArgumentException (while there are no arguments) without meaningful message.

Sample code:

        private async void GetFiles()
        {
            var storageItems = await Clipboard.GetContent().GetStorageItemsAsync();
            foreach(var item in storageItems)
            {
                if (item is StorageFolder folder)
                {
                    await folder.GetFilesAsync();
                }
            }
        }

Exception

System.ArgumentException:“Value does not fall within the expected range.”

OS version: Windows 10 16299.19
Target version: Windows 10 build 15063
Minimum version: Windows 10 build 15063
Microsoft.NETCore.UniversalWindowsPlatform package version: 5.4.0/5.4.1/6.0.1

Relevant pages:

• MediaPlaybackState
• MediaPlayerState

MediaPlaybackState has a note which says it may no longer be available after 1607 and MediaPlayerState should be used instead.

However, MediaPlayerState has an attribute which says it's deprecated.

So both enums are marked as deprecated. Is this a mistake?

Adam Comella
Microsoft Corp.

Relevant API: Windows.ApplicationModel.AppService.AppServiceConnection

After reading the documentation for this class, I have the following questions which I think the documentation should answer:

• Delivery contract. If I send a message with SendMessageAsync, is it guaranteed to be delivered to the recipient? Or are there cases where delivery can fail (e.g. the AppServiceConnection closes, the app gets suspended, the app terminates/crashes)? If a message fails to be delivered, how is this communicated to the sender?
• Event ordering contract. When multiple messages are sent, is RequestReceived expected to fire in the same order that the messages were sent? Is it possible for me to get a RequestReceived after ServiceClosed fires? These answers seem uncertain to me because all I know about AppServiceConnection's event contract is that the events fire on thread pool threads. Consequently, it seems plausible to me that different AppServiceConnection events could happen to run on different thread pool threads and so the ordering of the event handlers running could depend on the scheduling of the threads. So I'm wondering if AppServiceConnection's implementation guarantees an ordering for the running of event handlers.

Adam Comella
Microsoft Corp.

When a user requests markdown updates for new files, the service should create new stubs provided by the build/transform service and create new files into the target repo & branch.

Examples are using styles that are not supported in Windows 10.

Hi there!
According to this page, most of the methods are marked as Not supported.. Please point out the alternative methods to those unsupported ones :).
IMHO a VpnPacketBufferList object shouldn't be immutable.

https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.networking.vpn/vpnpacketbufferlist_append_1519252907.md
https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.networking.vpn/vpnpacketbufferlist_addatbegin_136422118.md
https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.networking.vpn/vpnpacketbufferlist_append_1519252907.md
https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.networking.vpn/vpnpacketbufferlist_clear_556466.md

https://docs.microsoft.com/en-us/uwp/api/windows.storage.streams.datawriterstoreoperation

Data​Writer​Store​Operation::GetResults() returns uint, but it's not documented, what does this uint represent. From the sample for DataWriter it can be seen that it's the number of stored bytes, but the meaning should be clear from the function documentation.

Is this the right place to report this stuff? There's a ton of issues like this in new docs.microsoft.com :-(, but I see only ~20 issues in the database.

J.

Hi,

Description of User::NonRoamableId here would use some details.

Like when it's guaranteed to stay the same and when not. From my observations:

• It's different for the same user on different machines (that's understandable, it's nonroamable).
• It seems to be different, when the same user logs in locally and remotely.
• It seems to stay the same after the restart.
• It seems to be different in each app for the same user on the same machine but.

Or if it's guaranteed to be different for two local users (i.e. not domain users) on different machines.

I was not sure whether I can use it to reliably identify the user or not, so I had to do all this tests myself.

Thanks,
J.

https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.ui.xaml.input/xyfocusnavigationstrategy.md

I came across SystemNavigationManager doc page and tried to use JS example presented there, however, it turned out that it has a flaw in event naming convention.

The example says it's backRequested but it doesn't work because all events names in WinRT JS API are lowercased so I tried with backrequested and it works.

I wanted to edit the doc page but I noticed that its file doesn't contain code samples. Is it possible to fix it or they are somehow magically generated from the C# API?

I've been searching and searching and cannot find a definitive answer to this issue. It is not specifically a winrt-api issue, but it is my inability to view these docs in the offline Help Viewer that raises the larger question. As I understand, MicrosoftDocs here on GitHub.com is the new hotness, but Help Viewer doesn't seem to understand this, because the list of "online resources" is quite short and non-comprehensive, nor does it seem to offer any method for connecting to the GitHub repo to subscribe to documentation sets.

I am brand new to Windows development (coming from macOS/iOS development on Xcode), wanting to start with the latest technology as my baseline moving forward (I have no legacy platform development needs). As I understand, Windows UWP app development via C# and the WinRT APIs is the Redmond-recommended platform moving forward. And yet, Visual Studio 2017 Help Viewer cannot provide the documentation contained in this repo.

Am I missing something? Is there a piece to this puzzle that connects Visual Studio offline documentation to these GitHub repos? Is Help Viewer deprecated in favor of these and a Markdown extension within VS2017? How can API lookups in VS2017 connect to their GitHub doc explanations?

In TimeTrigger class documention you claim that: "TimeTriggers, and other background triggers, do not work when the device is in battery saver mode."

This is not true for all triggers, as at least ToastNotificationHistoryChangedTrigger and ToastNotificationActionTrigger do work even when device is in battery saver mode.

I wanted to pick a logging solution for my C# UWP app and found the number of options to be overwhelming:

• System.Diagnostics.Debug
• System.Diagnostics.Trace
• System.Diagnostics.Tracing
• Windows.Foundation.Diagnostics.LoggingChannel

I couldn't find any document which describes the relationship between all of these APIs. What are the trade offs between these APIs? Which ones are recommended for which use cases?

I want to pick the right logging API up front so that my team doesn't end up having to rewrite all of our logging code later after we learn what the right option would have been the hard way through experience.

Picking a logging API is a problem that every serious UWP app team has to do. It would be nice to have a document that summarizes the UWP logging options, their relationships, their trade offs, and makes some recommendations. This is nicer than the current state of each app team having to study each logging API and try to guess at the relationships and trade offs between all of the options.

Adam Comella
Microsoft Corp.

Hi, the docs say there is a method to create strokes from inkpoints which accepts date time as parameters, however no method seems to exist, is that expected or when will this be available?
https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.ui.input.inking/inkstrokebuilder_createstrokefrominkpoints_2009821049.md

Source

A couple of field descriptions of this enum start with "Introduced in ." Notice the blank between "in" and the period. It seems like there's a missing word there.

Adam Comella
Microsoft Corp.

Setting the dark-theme in the docs (https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.symbolicon) causes that the Symbols are difficult to see.

The documentation shows method declarations in each supported language and has sections labeled C++, C#, VB, and JavaScript.

I would expect each declaration to appear under the section for the appropriate language.

Instead, all of the declarations appear under the JavaScript section.

Additionally, the "Copy" buttons don't appear to work. When I click the "Copy" button for C++ this is what is copied to my clipboard: // You can use this method in JavaScript..

Here's an example screenshot from Windows.ApplicationModel.AppService.AppServiceConnection:

Adam Comella
Microsoft Corp.

On this page the second edit link in the fields section leads me to a 404.

MSApp.getHtmlPrintDocumentSourceAsync(document).then(function (source) {
args.setSource(source);
});

The above code is not working for printing the complete document if document content is more than one page.

For example:-
https://docs.microsoft.com/en-us/uwp/api/windows.devices.radios.radio#Windows_Devices_Radios_Radio_GetRadiosAsync
The method returns an IAsyncOperation<IVectorView> but it is shown in the C# syntax block as
IAsyncOperation>
Notice the mismatched brackets.
For C# this should be displayed as:-
IAsyncOperation<IReadOnlyList>
The VisualBasic and C++ versions are also wrong (though C++ should display the IVectorView type as it is the raw WinRT type rather than IReadOnlyList which is the .NET mapping).
I suspect this could also be a problem for other async methods which return collections.

I feel some document has some classes provide incomplete examples...

For example, take a look at GridView Class. With the code:

<GridView ItemsSource="{Binding Source={StaticResource cvsProjects}}"
<!-- ... -->

I don't see the cvsProjects class anywhere in the example, so I cannot copy / paste the examples to play around with it in order to understand how it works.

It would be nice if the cvsProjects or an example class was shown so we could use it with the rest of the examples.

Affected API: Windows.ApplicationModel.Calls.VoipCallCoordinator.ReserveCallResourcesAsync

The only thing the documentation says about this API is "Reserves the resources necessary for a VoIP call.". It doesn't answer questions such as:

• When/why do I need to call this?
• If my app is handling 2 VoIP calls simultaneously, do I have to invoke this API once per VoIP call?
• What kind of resources is it reserving?
• Do I need to free them? When? How?
• What exceptions is this expected to throw? Looking at the VoIP sample, it appears that it's okay for ReserveCallResourcesAsync to throw an Exception with HRESULT -2147024713.

Adam Comella
Microsoft Corp.

Here, you find this text: "For apps written using the .NET Framework 4.5 in C# and VB.NET, the Close method is exposed as the method on the StreamSocket."
It should be "For apps written using the .NET Framework 4.5 in C# and VB.NET, the Close method is exposed as the Dispose() method on the StreamSocket."

The attached screenshot shows the inherited members for the Windows.UI.Xaml.Controls.Button class. It's impossible to work with because it's just an unstructured list. It's missing information on which class in the hierarchy each member comes from.
The old style documentation listed all members within fields, properties, methods and events and showed "Inherited from UIElement" for example and the hyperlinks went through to the correct type.

It seems that there are many links in the AutomationProperties doc which should navigate to another page but instead don't navigate anywhere.

Let's take Windows.UI.Xaml.Automation.AutomationProperties.AccessibilityViewProperty as an example:

• MSDN doc
• GitHub source

The beginning of the documentation for that property starts with "Identifies the AutomationProperties.AccessibilityView...". The last word, "AutomationProperties.AccessibilityView", is a link which brings me to the exact same part of the documentation I was looking at. However, I believe that link should have brought me here instead.

It seems this kind of mistake is made all over the AutomationProperties documentation

Adam Comella
Microsoft Corp.

Projected members need to be added to the api member surface for affected types.

Implement filtering logic to insert member level requirements where they differ from parent type

It says this property is "A value to show progress in the shell", but don't know where it actually shows. If currently it doesn't actually show a progress in the shell, the doc should inform API users of this.

File directory:
winrt-api/windows.applicationmodel.extendedexecution/extendedexecutionsession_percentprogress.md

The HID usages table from https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.ui.input/pointerpointproperties_hasusage_907430020.md#-remarks is not rendered correctly. See screenshot from https://docs.microsoft.com/en-us/uwp/api/windows.ui.input.pointerpointproperties#Windows_UI_Input_PointerPointProperties_HasUsage_System_UInt32_System_UInt32_:

For example GetDeviceSelectorForPairingStatus is new to Creators Update - but there is no way to tell this from the documentation. The BluetoothLEDevice page indicates support from 10.0.10240.

https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.devices.bluetooth/bluetoothledevice_getdeviceselectorfromconnectionstatus_401358086.md

On many pages the XAML code examples are invisible. They exist in the source code of the page, but they have the hidden attribute applied.

See for example:
https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.flipview#examples
https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.grid#examples

I suspect this affects all samples that are embedded using [!code-xml] syntax.

Samples using ```xaml are unaffected.

The documentation doesn't state how CharacterReceivedEventArgs.KeyCode is encoded.
However, I've found this answer on stackoverflow that claims that .Net's Convert.ToChar will do the trick:
http://stackoverflow.com/questions/16783820/handling-virtualkey-in-windows-8-store-apps-with-c-sharp

So I assume that it is a UTF32 character. Can somebody please clarify and note the correct usage in the documentation?

Alpha sort of inherited members would improve output.
Use short name instead of fully-qualified.

Add Parent element to inherited members

Tags should be:

Inherited properties
Inherited methods
Inherited events

Sample Parent entry:

• uid: System.Object.ReferenceEquals(System.Object,System.Object)
    commentId: M:System.Object.ReferenceEquals(System.Object,System.Object)
    parent: Inherited zzzzz
    isExternal: true
    name: ReferenceEquals(Object, Object)
    nameWithType: Object.ReferenceEquals(Object, Object)
    fullName: System.Object.ReferenceEquals(System.Object, System.Object)
    spec.csharp:

Projected types need to be translated based on syntax.

https://msdn.microsoft.com/en-us/library/hh694558(v=vs.110).aspx

https://github.com/dotnet/coreclr/blob/master/src/inc/winrtprojectedtypes.h

https://docs.microsoft.com/en-us/uwp/api/windows.foundation.uri

at the "Extension" section it says that dot is not included, however when I test it with this url:
https://scontent.xx.fbcdn.net/v/t31.0-8/337554_209649659128630_1763982397_o.jpg?oh=2d3876f819bd76bffee7e7131e45b4ad&oe=5A6599

The extension it returns me is ".jpg", which does have the dot (.)

Why is there no setter to directly manipulate the Frame Rate and, not make your own?

Need syntax for projection types

Please, describe cases when the ctor can throw for example FileNotFound exception here
https://github.com/MicrosoftDocs/winrt-api/blob/docs/windows.media.speechsynthesis/speechsynthesizer_speechsynthesizer_1221375020.md
or here https://docs.microsoft.com/en-us/uwp/api/windows.media.speechsynthesis.speechsynthesizer#remarks

I was just reading this page:
https://docs.microsoft.com/en-us/uwp/api/windows.ui.core.coredispatcher
and I noticed, that in all places where a specific CoreDispatcherPriority enum value is used, the actual value is not shown in the article, only the type. Because of this issue lots of parts of the text does not make any sense:

It's possible this issue with enum values is on much more MSDN pages.

In the old documentation you could view the numeric values for each member but now this information is not displayed. The values are present in the raw markdown content.

winrt-api/windows.applicationmodel/package_getapplistentriesasync_364802562.md

Text states:
Enumerates the packaged apps on the device. Only packaged apps that are registered to the current user are returned.
This is incorrect. Actually only apps included within the current package are enumerated.

Like here:
https://docs.microsoft.com/en-us/uwp/api/windows.devices.enumeration.devicewatcher#events_

DeviceWatcher::EnumerationCompleted event is declared like this:

public event TypedEventHandler EnumerationCompleted

But it should be:

public event TypedEventHandler<DeviceWatcher^, Object^> EnumerationCompleted

Also the description of parameters of generic type is missing. E.g. what does the Object^ parameter represent?

I can see this throughout the whole UWP documentation at docs.microsoft.com.

J.

Primitive types differ by devlang. Our docs need to reflect the differences.

C++
https://msdn.microsoft.com/en-us/library/windows/apps/hh710417.aspx

https://msdn.microsoft.com/en-us/library/windows/apps/hh699871.aspx

VB.Net
http://www.dotnetheaven.com/article/data-types-in-vb.net1

(Task 11010772)

Referring to winrt-api/windows.applicationmodel/startuptask.md

It says there is no "StartupPage" attribute declared under <uap5:StartupTask> tag when compiling confirmed here: https://docs.microsoft.com/en-us/uwp/schemas/appxpackage/uapmanifestschema/element-uap5-startuptask

Shouldn't the "StartupPage" actually be the "StartPage" attribute under <uap5:Extension> tag?

Like this:

    <uap5:Extension Category="windows.startupTask" StartPage="EntryPage">
      <uap5:StartupTask
        TaskId="MyStartupId"
        DisplayName="Test startup"  />            
    </uap5:Extension>

New style of the docs, where everything is in one page (class description, and detailed descriptions of all its properties, events, methods, ...) is hard to read. It's hard to get an overview from this layout, it's overwhelming. Structuring would help. Like in the old msdn docs, where you had class description on one page, together with table of properties, events, methods with SHORT description of each. And each property/event/method had separate page with detailed description.

Example of bad, "all in one page" documentation, FrameworkElement:
https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.frameworkelement

Example of good, structured documentation, IDirect3DDevice9:
https://msdn.microsoft.com/en-us/library/windows/desktop/bb174336(v=vs.85).aspx

I wonder whose idea it was to ruin the good old msdn documentation like this... :-(. Pardon my expressive language.

Why can't you Microsoft people add a "Watermark" Property to TextBlock and ComboBoxs that adds a watermark label to left or inside and above the content for telling people what the TextBox or ComboBox is for?? I hate writing garage templates to do the same thing. It should be built into the component in my opinion. Example:

The Effect this Achieves without all the garbage:

        <Grid>
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="auto"/>
                <ColumnDefinition Width="*"/>
            </Grid.ColumnDefinitions>
            <Grid.RowDefinitions>
                <RowDefinition Height="auto"/>
            </Grid.RowDefinitions>
            <TextBlock Grid.Row="0" Grid.Column="0" Text="Rate" FontSize="10" Padding="3,0,0,0"/>
            <TextBox Grid.Row="0" Grid.Column="0" Padding="0,10,0,0" Margin="0" Text="1.0" FontSize="12"/>
        </Grid>

Affected API: Windows.ApplicationModel.Calls.VoipCallCoordinator.SetupNewAcceptedCall

The documentation for this API is missing some details. Under what scenarios would I want to use this API? How does this API compare to RequestNewIncomingCall?

Adam Comella
Microsoft Corp.