Merge pull request #89 from microsoft/pete-dev

Prep for a developer preview of the SDK Shape

get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md

@@ -0,0 +1,56 @@
+# Consuming the Windows MIDI Services SDK
+
+The Windows MIDI Services SDK is built using C++/WinRT. WinRT, a requirement for modern APIs on Windows, enables desktop applications, regardless of language, to be able to use APIs, SDKs, etc. that we create. The older tools, C++/CX, are arguably simpler to implement in, but because they include proprietary extensions to C++, we decided to go with standards-based C++/WinRT instead.
+
+## Prerequisites
+
+To use the SDK (or underlying API) your application language and tools must be able to work with WinRT metadata and libraries.
+
+* Visual Studio 2022 if you are using Visual Studio
+* Windows SDK 10.0.20348 (Install with Visual Studio)
+* Windows 10 22H2, or preferably, the latest version of Windows 11. Our development machines are all running Windows 11.
+* C++ 17 (C++ 20 may work, C++ 14 will not)
+
+Note that there are somewhat hacky ways to get traditional C to work with the COM interfaces, but it is a ton of work for you, and is not a scenario we support. If you find yourself in that situation, I recommend factoring out the MIDI code into its own lib and encapsulating all the C++ calls in there.
+
+## Consuming from C++
+
+Add the C++/WinRT Nuget package to your C++ project in Visual Studio. This installs the required tools and build process. See the C++/WinRT FAQ link below for using LLVM/Clang. Note that the Windows MIDI Services team does not provide any support for LLVM/Clang, but we will take PRs as required if we need to change something reasonable to ensure you are successful with those tools, within what C++/WinRT can support.
+
+Download the compiled winmd packages from Github. (We may offer another way to handle this in the future, but Nuget packages can't modify C++ projects in the same way they can C# and others)
+
+Modify the project file as required (info in the C++/WinRT docs, and you can also look at the sample application code). If you are not using Visual Studio as your toolchain for your project, you may want to pull out the MIDI code into a library in your project which does. It's not strictly required, but it's much easier. (If you do not want to do this, you'll need to manually set up the cppwinrt tools as part of your build process).
+
+[Read through this page](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/consume-apis), specifically the "If the API is implemented in a Windows Runtime component". For the SDK, the calls are NOT in a Windows namespace, although that section can be useful to read.
+
+After that, you reference the types as you would anything else in C++. Only the toolchain is an extra step. What it produces is standard C++. We're considering what we can do here to possibly eliminate even that step in the future, but it's required for now.
+
+* [C++ Windows MIDI Services Example Code](https://github.com/microsoft/midi/get-started/midi-developers/app-developers/samples/cpp-winrt/)
+* [Introduction to C++/WinRT](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/)
+* [C++/WinRT on GitHub](https://github.com/microsoft/cppwinrt)
+* [C++/WinRT FAQ](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/faq)
+* [C++/WinRT Troubleshooting](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/troubleshooting)
+
+## Consuming from C# Desktop App
+
+Your project will currently need to target .NET 7 or above. We are considering support for .NET Framework and lower versions of .NET like .NET 6. However, that is neither confirmed nor promised.
+
+Releases will eventually be in the official Nuget.org package source. For now, you can create a local package source and place the NuGet package in there. Then add it to your package sources in the NuGet Package Manager in Visual Studio.
+
+The package contains the .NET (C#) projection for .NET 7 and above. You will still need to install the C#/WinRT NuGet package in your project because we leverage Windows.Devices.Enumeration and other Windows SDK types.
+
+**Note that other .NET languages (like Visual Basic) may work, but have not been tested.**
+
+* [C# Windows MIDI Services Example Code](https://github.com/microsoft/midi/get-started/midi-developers/app-developers/samples/csharp-net/)
+* [C#/WinRT on GitHub](https://github.com/microsoft/cswinrt)
+
+## Consuming from C# UWP
+
+Support for this is not yet in place. We are evaluating.
+
+## Consuming from RS
+
+We will provide more information in the future. However, you will follow a similar approach to C++ using RS/WinRT instead of C++/WinRT. Note that teh Rust WinRT tools are newer and are still in active development. Supporting non-Windows SDK winmd files is or will be supported, but is not intuitive at the moment. **There is no existing crate for Windows MIDI Services right now.**
+
+* [Rust Windows MIDI Services Example Code](https://github.com/microsoft/midi/get-started/midi-developers/app-developers/samples/rust-winrt/)
+* [RS/WinRT on GitHub](https://github.com/microsoft/windows-rs)

src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec

@@ -2,7 +2,7 @@
 <package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
 	<metadata>
 		<id>Microsoft.Devices.Midi2.Core.CS</id>
-		<version>0.1.8-prerelease</version>
+		<version>1.0.0-preview.1-0033</version>
 		<authors>Microsoft Corporation</authors>
 		<description>Windows MIDI Services core application SDK. Minimum package necessary to use Windows MIDI Services from an app.</description>
 		<license type="expression">MIT</license>
@@ -40,8 +40,8 @@
 		<!--Architecture-specific implementation DLLs should be copied into RID-relative folders-->
 		<file src="..\..\_build\x64\Debug\Microsoft.Devices.Midi2.Core\bin\Microsoft.Devices.Midi2.Core\Microsoft.Devices.Midi2.Core.dll" 
 			  target="runtimes\win10-x64\native\Microsoft.Devices.Midi2.Core.dll" />
-		<file src="..\..\_build\x64\Debug\Microsoft.Devices.Midi2.Core\bin\Microsoft.Devices.Midi2.Core\Microsoft.Devices.Midi2.pri"
-			  target="runtimes\win10-x64\native\Microsoft.Devices.Midi2.pri" />
+<!--		<file src="..\..\_build\x64\Debug\Microsoft.Devices.Midi2.Core\bin\Microsoft.Devices.Midi2.Core\Microsoft.Devices.Midi2.pri"
+			  target="runtimes\win10-x64\native\Microsoft.Devices.Midi2.pri" /> -->
 
 
 	</files>

src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h

@@ -8,7 +8,8 @@
 
 #pragma once
 
-#define MIDI_APP_SDK_VERSION 1.0
+// this should be kept in sync with the nuspec. Manual for now.
+#define MIDI_APP_SDK_VERSION_STRING L"1.0.0-preview"
 
 // TODO: Need to include minimum compat API version info here?
 

src/app-dev-sdk/sdk-core/MidiServices.cpp

@@ -11,6 +11,8 @@
 #include "MidiServices.h"
 #include "MidiServices.g.cpp"
 
+#include "MidiAppSdkVersion.h"
+
 namespace winrt::Microsoft::Devices::Midi2::implementation
 {
     bool MidiServices::CheckForWindowsMidiServices(winrt::Microsoft::Devices::Midi2::WindowsMidiServicesCheckError& errorResult)
@@ -23,7 +25,7 @@ namespace winrt::Microsoft::Devices::Midi2::implementation
     }
     hstring MidiServices::SdkVersion()
     {
-        throw hresult_not_implemented();
+        return MIDI_APP_SDK_VERSION_STRING;
     }
     hstring MidiServices::MinimumCompatibleMidiServicesVersion()
     {