From ec24689e96193103499c854876fc71f740f0e51b Mon Sep 17 00:00:00 2001 From: Pete Brown Date: Mon, 26 Jun 2023 15:34:17 -0400 Subject: [PATCH 1/2] Prep for a developer "view" release of the SDK --- .../app-developers/docs/consuming-midi-sdk.md | 46 +++++++++++++++++++ .../app-developers/samples/cpp-juce/README.md | 5 -- .../app-developers/samples/flutter/README.md | 5 -- .../samples/js-electron/README.md | 5 -- .../Microsoft.Devices.Midi2.Core.CS.nuspec | 4 +- src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h | 3 +- src/app-dev-sdk/sdk-core/MidiServices.cpp | 4 +- 7 files changed, 53 insertions(+), 19 deletions(-) create mode 100644 get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md delete mode 100644 get-started/midi-developers/app-developers/samples/cpp-juce/README.md delete mode 100644 get-started/midi-developers/app-developers/samples/flutter/README.md delete mode 100644 get-started/midi-developers/app-developers/samples/js-electron/README.md diff --git a/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md b/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md new file mode 100644 index 00000000..9b11130c --- /dev/null +++ b/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md @@ -0,0 +1,46 @@ +# Consuming the Windows MIDI Services SDK + +To use the SDK (or underlying API) your application language and tools must be able to work with WinRT metadata and libraries. + +## Consuming from C++ + +Add the C++/WinRT Nuget package to your C++ project. + +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. 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) + + +## 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. + +**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) + diff --git a/get-started/midi-developers/app-developers/samples/cpp-juce/README.md b/get-started/midi-developers/app-developers/samples/cpp-juce/README.md deleted file mode 100644 index 8077b786..00000000 --- a/get-started/midi-developers/app-developers/samples/cpp-juce/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using Windows MIDI Services from C++ with JUCE - -## Building the Samples - -More information coming as the project progresses \ No newline at end of file diff --git a/get-started/midi-developers/app-developers/samples/flutter/README.md b/get-started/midi-developers/app-developers/samples/flutter/README.md deleted file mode 100644 index 56f40cb0..00000000 --- a/get-started/midi-developers/app-developers/samples/flutter/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using Flutter with Windows MIDI Services - -## Building the Samples - -More information coming as the project progresses \ No newline at end of file diff --git a/get-started/midi-developers/app-developers/samples/js-electron/README.md b/get-started/midi-developers/app-developers/samples/js-electron/README.md deleted file mode 100644 index 1745d278..00000000 --- a/get-started/midi-developers/app-developers/samples/js-electron/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using Electron / JS with Windows MIDI Services - -## Building the Samples - -More information coming as the project progresses diff --git a/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec b/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec index fa6d96d2..5ace83a2 100644 --- a/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec +++ b/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec @@ -40,8 +40,8 @@ - + diff --git a/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h b/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h index d9a3588a..eb14bb69 100644 --- a/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h +++ b/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"0.0-prerelease" // TODO: Need to include minimum compat API version info here? diff --git a/src/app-dev-sdk/sdk-core/MidiServices.cpp b/src/app-dev-sdk/sdk-core/MidiServices.cpp index 5ddc7ec4..0c144a78 100644 --- a/src/app-dev-sdk/sdk-core/MidiServices.cpp +++ b/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() { From 7582979b4fea997be2dfb19efebf3347ba02ee2e Mon Sep 17 00:00:00 2001 From: Pete Brown Date: Mon, 26 Jun 2023 16:03:39 -0400 Subject: [PATCH 2/2] Prep for developer preview of SDK shape --- .../app-developers/docs/consuming-midi-sdk.md | 22 ++++++++++++++----- .../Microsoft.Devices.Midi2.Core.CS.nuspec | 2 +- src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h | 2 +- 3 files changed, 18 insertions(+), 8 deletions(-) diff --git a/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md b/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md index 9b11130c..24f11c65 100644 --- a/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md +++ b/get-started/midi-developers/app-developers/docs/consuming-midi-sdk.md @@ -1,14 +1,25 @@ # 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. +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. 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). +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. @@ -17,7 +28,8 @@ After that, you reference the types as you would anything else in C++. Only the * [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 @@ -25,14 +37,13 @@ Your project will currently need to target .NET 7 or above. We are considering s 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. +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. @@ -43,4 +54,3 @@ We will provide more information in the future. However, you will follow a simil * [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) - diff --git a/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec b/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec index 5ace83a2..cf807ec7 100644 --- a/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec +++ b/src/app-dev-sdk/sdk-core-projection-cs/nuget/Microsoft.Devices.Midi2.Core.CS.nuspec @@ -2,7 +2,7 @@ Microsoft.Devices.Midi2.Core.CS - 0.1.8-prerelease + 1.0.0-preview.1-0033 Microsoft Corporation Windows MIDI Services core application SDK. Minimum package necessary to use Windows MIDI Services from an app. MIT diff --git a/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h b/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h index eb14bb69..7a39ef2f 100644 --- a/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h +++ b/src/app-dev-sdk/sdk-core/MidiAppSdkVersion.h @@ -9,7 +9,7 @@ #pragma once // this should be kept in sync with the nuspec. Manual for now. -#define MIDI_APP_SDK_VERSION_STRING L"0.0-prerelease" +#define MIDI_APP_SDK_VERSION_STRING L"1.0.0-preview" // TODO: Need to include minimum compat API version info here?